\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename scm.info
@settitle SCM
@setchapternewpage on
@c Choices for setchapternewpage are {on,off,odd}.
@paragraphindent 2
@c %**end of header

@iftex
@finalout
@c DL: lose the egregious vertical whitespace, esp. around examples
@c but paras in @defun-like things don't have parindent
@parskip 4pt plus 1pt
@end iftex

@titlepage
@title SCM
@subtitle Scheme Implementation
@subtitle Version 4e2
@subtitle January 1995
@author by Aubrey Jaffer

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Aubrey Jaffer

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end titlepage

@node Top, Copying, (dir), (dir)

@ifinfo
This file documents the SCM Scheme implementation.

Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Aubrey Jaffer

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
@end ifinfo

@menu
* Copying::                     
* Overview::                    Whats here and how to start using it.
* Installing SCM::              
* Standard Facilities::         
* Packages::                    Optional Capabilities
* Guile Facilities::            Brave new World
* Internals::                   How it works
* Procedure and Macro Index::   
* Variable Index::              
* Type Index::                  
@end menu

@node Copying, Overview, Top, Top
@chapter Copying

@center COPYRIGHT (c) 1989 BY
@center PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS.
@center ALL RIGHTS RESERVED

@noindent
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.

@noindent
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.

@noindent
gjc@@paradigm.com
@flushright
Phone: 617-492-6079
@end flushright
@flushleft
Paradigm Associates Inc
29 Putnam Ave, Suite 6
Cambridge, MA 02138
@end flushleft

@sp 2

@center Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995
@center Free Software Foundation, Inc.
@center 675 Mass Ave, Cambridge, MA 02139, USA

@noindent
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.

@center NO WARRANTY

@noindent
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.

@noindent
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.

@node Overview, Installing SCM, Copying, Top
@chapter Overview

@noindent
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::                 
* Bibliography::                
* Invoking SCM::                
* SCM Options::                 
* SCM Variables::               
* SCM Examples::                
* SCM Session::                 
@end menu

@node SCM Features, SCM Authors, Overview, Overview
@section Features

@itemize @bullet
@item
Conforms to Revised^4 Report on the Algorithmic Language Scheme [R4RS]
and the [IEEE] P1178 specification.
@item
Support for [SICP], [R2RS], [R3RS], and (proposed) [R5RS] scheme code.
@item
Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos, VMS,
Unix and similar systems.  Supports ASCII and EBCDIC character sets.
@item
Is fully documented in @TeX{}info form, allowing documentation to be
generated in info, @TeX{}, html, nroff, and troff formats.
@item
Supports inexact real and complex numbers, 30 bit immediate integers and
large precision integers.
@item
Many Common Lisp functions: @code{logand}, @code{logor}, @code{logxor},
@code{lognot}, @code{ash}, @code{logcount}, @code{integer-length},
@code{bit-extract}, @code{defmacro}, @code{macroexpand},
@code{macroexpand1}, @code{gentemp}, @code{defvar}, @code{force-output},
@code{software-type}, @code{get-decoded-time},
@code{get-internal-run-time}, @code{get-internal-real-time},
@code{delete-file}, @code{rename-file}, @code{copy-tree}, @code{acons},
and @code{eval}.
@item
@code{Char-code-limit}, @code{most-positive-fixnum},
@code{most-negative-fixnum}, @code{and internal-time-units-per-second}
constants.  @code{*Features*} and @code{*load-pathname*} variables.
@item
Arrays and bit-vectors.  String ports and software emulation ports.
I/O extensions providing ANSI C and POSIX.1 facilities.
@item
Interfaces to standard libraries including REGEX string regular
expression matching and the CURSES screen management package.
@item
Available add-on packages including an interactive debugger, database,
X-window graphics, BGI graphics, Motif, and Open-Windows packages.
@item
A compiler (HOBBIT, available separately) and dynamic linking of
compiled modules.
@item
User definable responses to interrupts and errors,
Process-syncronization primitives.  Setable levels of monitoring and
timing information printed interactively (the @code{verbose} function).
@code{Restart}, @code{quit}, and @code{exec}.
@end itemize

@node SCM Authors, Bibliography, SCM Features, Overview
@section Authors

@table @b
@item Aubrey Jaffer (jaffer@@ai.mit.edu)
Most of SCM.
@item Radey Shouman
Arrays. @code{gsubr}s, compiled closures, and records.
@item Jerry D. Hedden
Real and Complex functions.  Fast mixed type arithmetics.
@item Hugh Secker-Walker
Syntax checking and memoization of special forms by evaluator.  Storage
allocation strategy and parameters.
@item George Carrette
@dfn{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
(@pxref{Garbage Collection}).
@end table

@noindent
There are many other contributors to SCM.  They are acknowledged in the
file @file{ChangeLog}, a log of changes that have been made to scm.

@node Bibliography, Invoking SCM, SCM Authors, Overview
@section Bibliography

@table @asis
@item [IEEE]
@pindex IEEE
@cite{IEEE Standard 1178-1990.  IEEE Standard for the Scheme
Programming Language.}  IEEE, New York, 1991.

@item [Simply]
@pindex Simply
Brian Harvey and Matthew Wright.
@cite{Simply Scheme: Introducing Computer Science}
MIT Press, 1994 ISBN 0-262-08226-8

@item [SICP]
@pindex SICP
Harold Abelson and Gerald Jay Sussman with Julie Sussman.
@cite{Structure and Interpretation of Computer Programs.}
MIT Press, Cambridge, 1985.

@item [R4RS]
@pindex R4RS
William Clinger and Jonathan Rees, Editors.
@ifset html
<A HREF="r4rs_toc.html">
@end ifset
Revised(4) Report on the Algorithmic Language Scheme.
@ifset html
</A>
@end ifset
In @cite{ACM Lisp Pointers IV} (July-September 1991).
@ifinfo

@ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language
Scheme}.
@end ifinfo

@item [SLIB]
@pindex SLIB
Todd R. Eigenschink, Dave Love, and Aubrey Jaffer.
@ifset html
<A HREF="slib_toc.html">
@end ifset
SLIB, The Portable Scheme Library.
@ifset html
</A>
@end ifset
Edition 2.01, for SLIB version 2a2, January 1995.
@ifinfo

@ref{Top, , , slib, SLIB}.
@end ifinfo

@item [JACAL]
@pindex JACAL
Aubrey Jaffer.
@ifset html
<A HREF="jacal_toc.html">
@end ifset
JACAL Symbolic Mathematics System.
@ifset html
</A>
@end ifset
Version 1a5, April 1994.
@ifinfo

@ref{Top, , , jacal, JACAL}.
@end ifinfo
@end table

@table @file
@item scm.texi
@itemx scm.info
Documentation of @code{scm} extensions (beyond Scheme standards).
Documentation on the internal representation and how to extend or
include @code{scm} in other programs.
@end table

@node Invoking SCM, SCM Options, Bibliography, Overview
@section Invoking SCM

@quotation
@exdent @b{ scm } [-a @i{kbytes}] [-ibvqmu] [-p @i{number}]
@w{[-c @i{expression}]} @w{[-e @i{expression}]} @w{[-f @i{filename}]}
@w{[-l @i{filename}]} @w{[-r @i{feature}]} @w{[-- | - | -s]}
@w{[@i{filename}]} @w{[@i{arguments} @dots{}]}
@end quotation

@noindent
Upon startup @code{scm} loads the file specified by by the environment
variable @var{SCM_INIT_PATH} or by the parameter @var{IMPLINIT} in the
makefile (or @file{scmfig.h}) if @var{SCM_INIT_PATH} is not defined. The
makefiles attempt to set @var{IMPLINIT} to @file{Init.scm} in the source
directory.

@noindent
Unless the option @code{-no-init-file} occurs in the command line,
@file{Init.scm} checks to see if there is file @file{ScmInit.scm} in the
path specified by the environment variable @var{HOME} (or in the current
directory if @var{HOME} is undefined). If it finds such a file it is
loaded.

@noindent
@file{Init.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.

@noindent
This explanation applies to SCMLIT or other builds of SCM.  GUILE is
invoked similarly to SCM.  Guile's startup script is @file{Ginit.scm}
rather than @file{Init.scm}.

@noindent
Scheme-code files can also invoke SCM and its variants.  @xref{Syntax
Extensions, #!}.

@node SCM Options, SCM Variables, Invoking SCM, Overview
@section Options

@noindent
The options are processed in the order specified on the command line.

@deffn {Command Option} -a kbytes
specifies that @code{scm} should allocate an initial heapsize of
@var{kbytes}. This option, if present, must be the first on the command
line.
@end deffn

@deffn {Command Option} -no-init-file
Inhibits the loading of @file{ScmInit.scm} as described above.
@end deffn

@deffn {Command Option} -e expression
@deffnx {Command Option} -c expression
specifies that the scheme expression @var{expression} is to be
evaluated. These options are inspired by @code{perl} and @code{sh}
respectively. On Amiga systems the entire option and argument need to be
enclosed in quotes. For instance @samp{"-e(newline)"}.
@end deffn

@deffn {Command Option} -r feature
requires @var{feature}. This will load a file from [SLIB] if that
@var{feature} is not already supported. If @var{feature} is 2, 3, 4, or
5 @code{scm} will require the features neccessary to support [R2RS],
[R3RS], [R4RS], or proposed [R5RS], respectively.
@end deffn

@deffn {Command Option} -l filename
@deffnx {Command Option} -f filename
loads @var{filename}. @code{Scm} will load the first (unoptioned) file
named on the command line if no @code{-c}, @code{-e}, @code{-f},
@code{-l},  or @code{-s} option preceeds
it.
@end deffn

@deffn {Command Option} -p level
sets the prolixity (verboseness) to @var{level}. This is the same as
the @code{scm} command (verobse @var{level}).
@end deffn

@deffn {Command Option} -v
(verbose mode) specifies that @code{scm} will print prompts, evaluation
times, notice of loading files, and garbage collection statistics. This
is the same as @code{-p3}.
@end deffn

@deffn {Command Option} -q
(quiet mode) specifies that @code{scm} will print no extra
information. This is the same as @code{-p0}.
@end deffn

@deffn {Command Option} -m
specifies that subsequent loads, evaluations, and user interactions will
be with [R4RS] macro capability. To use a specific [R4RS] macro
implementation from [SLIB] (instead of [SLIB]'s default) put @code{-r}
@var{macropackage} before @code{-m} on the command line.
@end deffn

@deffn {Command Option} -u
specifies that subsequent loads, evaluations, and user interactions will
be without [R4RS] macro capability. [R4RS] macro capability can
be restored by a subsequent @code{-m} on the command line or from Scheme
code.
@end deffn

@deffn {Command Option} -i
specifies that @code{scm} should run interactively. That means that
@code{scm} will not terminate until the @code{(quit)} or @code{(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 @code{scm} is started from a tty, it will assume
that it should be interactive unless given a subsequent @code{-b}
option.
@end deffn

@deffn {Command Option} -b
specifies that @code{scm} should run non-interactively. That means that
@code{scm} will terminate after processing the command line or if there
are errors.
@end deffn

@deffn {Command Option} -s
specifies, by analogy with @code{sh}, that further options are to be
treated as program aguments.
@end deffn

@deffn {Command Option} -
@deffnx {Command Option} --
specifies that there are no more options on the command line.
@end deffn

@node SCM Variables, SCM Examples, SCM Options, Overview
@section Environment Variables

@defvr {Environment Variable} SCM_INIT_PATH
is the pathname where @code{scm} will look for its initialization
code. The default is the file @file{Init.scm} in the source directory.
@end defvr

@defvr {Environment Variable} SCHEME_LIBRARY_PATH
is the [SLIB] Scheme library directory.
@end defvr

@defvr {Environment Variable} HOME
is the directory where @file{Init.scm} will look for the user
initialization file @file{ScmInit.scm}.
@end defvr

@section Scheme Variables

@defvar *argv*
contains the list of arguments to the program. @code{*argv*} can change
during argument processing. This list is suitable for use as an argument
to [SLIB] @code{getopt}.
@end defvar

@defvar *R4RS-macro*
controls whether loading and interaction support [R4RS] macros. Define
this in @file{ScmInit.scm} or files specified on the command line. This
can be overridden by subsequent @code{-m} and @code{-u} options.
@end defvar

@defvar *interactive*
controls interactivity as explained for the @code{-i} and @code{-b}
options. Define this in @file{ScmInit.scm} or files specified on the
command line. This can be overridden by subsequent @code{-i} and
@code{-b} options.
@end defvar

@node SCM Examples, SCM Session, SCM Variables, Overview
@section Examples

@table @code
@item % scm foo.scm
Loads and executes the contents of @file{foo.scm} and then enters
interactive session.

@item % scm -f foo.scm arg1 arg2 arg3
Parameters @code{arg1}, @code{arg2}, and @code{arg3} are stored in the
global list @code{*argv*}; Loads and executes the contents of
@file{foo.scm} and exits.

@item % scm -s foo.scm arg1 arg2
Sets *argv* to @code{("foo.scm" "arg1" "arg2")} and enters interactive
session.

@item % scm -e `(write (list-ref *argv* *optind*))' bar
Prints @samp{"bar"}.

@item % scm -rpretty-print -r format -i
Loads @code{pretty-print} and @code{format} and enters interactive
session.

@item % scm -r5
Loads @code{dynamic-wind}, @code{values}, and [R4RS] macros and enters
interactive (with macros) session.

@item % scm -r5 -r4
Like above but @code{rev4-optional-procedures} are also loaded.
@end table

@node SCM Session,  , SCM Examples, Overview
@section SCM Session

@itemize @bullet
@item
Options, file loading and features can be specified from the command
line.  @xref{System interface, , , scm, SCM}.  @xref{Require, , , slib,
SLIB}.
@item
Typing the end-of-file character at the top level session (while SCM is
not waiting for parenthesis closure) causes SCM to exit.
@item
Typing the interrupt character aborts evaluation of the current form
and resumes the top level read-eval-print loop.
@end itemize

@node Installing SCM, Standard Facilities, Overview, Top
@chapter Installing SCM

@menu
* SLIB::                        
* Problems Compiling::          
* Problems Linking::            
* Problems Running::            
* Testing::                     
* Reporting Problems::          
@end menu

@node SLIB, Problems Compiling, Installing SCM, Installing SCM
@section SLIB

[SLIB] is a portable Scheme library meant to provide compatibility and
utility functions for all standard Scheme implementations.

Although SLIB is not @emph{neccessary} to run SCM, I strongly suggest
you obtain and install it.  Bug reports about running SCM without SLIB
have very low priority.  SLIB is available from the same sites as SCM:

@ifclear html
@itemize
@item
altdorf.ai.mit.edu:archive/scm/slib2a2.tar.gz
@item
prep.ai.mit.edu:pub/gnu/jacal/slib2a2.tar.gz
@item
ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a2.tar.gz
@item
ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a2.tar.gz
@end itemize
@end ifclear

@ifset html
<A HREF="file://ftp-swiss.ai.mit.edu/pub/scm/slib2a2.tar.gz">
ftp-swiss.ai.mit.edu:pub/scm/slib2a2.tar.gz
</A>
<A HREF="file://prep.ai.mit.edu/pub/gnu/jacal/slib2a2.tar.gz">
prep.ai.mit.edu:pub/gnu/jacal/slib2a2.tar.gz
</A>
<A HREF="file://ftp.maths.tcd.ie/pub/bosullvn/jacal/slib2a2.tar.gz">
ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a2.tar.gz
</A>
<A HREF="file://ftp.cs.indiana.edu/pub/scheme-repository/code/lib/slib2a2.tar.gz">
ftp.cs.indiana.edu:/pub/scheme-repository/code/lib/slib2a2.tar.gz
</A>
@end ifset

@node Problems Compiling, Problems Linking, SLIB, Installing SCM
@section Problems Compiling

@table @asis
@item FILE: PROBLEM
HOW TO FIX
@item *.c: include file not found
Correct the status of STDC_HEADERS in @file{scmfig.h}

fix #include statement or add #define for system type to
@file{scmfig.h}.
@item *.c: Function should return a value in @dots{}
@itemx *.c: Parameter '@dots{}' is never used in @dots{}
@itemx *.c: Condition is always false in @dots{}
@itemx *.c: Unreachable code in function @dots{}
Ignore.
@item scm.c: assignment between incompatible types
change SIGRETTYPE in @file{scm.c}.
@item time.c: CLK_TCK redefined
incompatablility between <stdlib.h> and <sys/types.h>.  remove
STDC_HEADERS in @file{scmfig.h}.

edit <sys/types.h> to remove incompatability.
@item subr.c: Possibly incorrect assignment in function lgcd
Ignore.
@item sys.c: statement not reached
@itemx sys.c: constant in conditional expression
ignore
@item sys.c: `???' undeclared, outside of functions
#undef STDC_HEADERS in @file{scmfig.h}.
@item scl.c: syntax error
#define SYSTNAME to your system type in @file{scl.c} (softtype)
@end table

@node Problems Linking, Problems Running, Problems Compiling, Installing SCM
@section Problems Linking

@table @asis
@item PROBLEM
HOW TO FIX
@item _sin etc. missing.
uncomment LIBS in makefile
@end table

@node Problems Running, Testing, Problems Linking, Installing SCM
@section Problems Running

@table @asis
@item PROBLEM
HOW TO FIX
@item Opening message and then machine crashes.
Change memory model option to C compiler (or makefile).

Make sure @code{sizet} definition is correct in @file{scmfig.h}.

Reduce size of HEAP_SEG_SIZE in @file{setjump.h}.
@item Input hangs
#define NOSETBUF
@item ERROR: heap: need larger initial
Need to increase the initial heap allocation using -a<kbytes> or
INIT_HEAP_SIZE.
@item ERROR: Could not allocate @dots{}
Check @code{sizet} definition.

Use 32 bit compiler mode.

Don't try to run as subproccess
@item remove @dots{} in scmfig.h and recompile scm
@itemx add @dots{} in scmfig.h and recompile scm
Do it and recompile files.
@item ERROR: @file{Init.scm} not found
Assign correct IMPLINIT in makefile or @file{scmfig.h} or define
environment variable @code{SCM_INIT_PATH} to be the full pathname of
@file{Init.scm} (@pxref{Installing SCM}).
@item WARNING: require.scm not found
define environment variable @code{SCHEME_LIBRARY_PATH} to be the full
pathname of the scheme library [SLIB] or change @code{library-vicinity} in
@file{Init.scm} to point to library or remove. @xref{Installation, , , slib,
SLIB}.

Make sure the value of @code{(library-vicinity)} has a trailing file
separator (like @key{/} or @key{\}).
@end table

@node Testing, Reporting Problems, Problems Running, Installing SCM
@section Testing

@noindent
Loading @file{test.scm} in the distribution will run an [R4RS]
conformance test on @code{scm}.

@example
> (load "test.scm")
@print{}
;loading "test.scm"
SECTION(2 1)
SECTION(3 4)
 #<primitive-procedure boolean?>
    #<primitive-procedure char?>
       #<primitive-procedure null?>
          #<primitive-procedure number?>
@dots{}
@end example

@noindent
Loading @file{pi.scm} in the distribution will enable you to compute
digits of pi.

@example
> (load "pi")
;loading "pi"
;done loading "pi.scm"
;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other
#<unspecified>
> (pi 100 5)
00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
70679
;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other
#<unspecified>
@end example

@table @asis
@item PROBLEM
HOW TO FIX
@item Runs some and then machine crashes.
See above under machine crashes.
@item Runs some and then ERROR: @dots{} (after a GC has happened)
Remove optimization option to C compiler and recompile.

@code{#define SHORT_ALIGN} in @file{scmfig.h}.
@item Some symbol names print incorrectly.
Change memory model option to C compiler (or makefile).

Check that @code{HEAP_SEG_SIZE} fits within @code{sizet}.

Increase size of @code{HEAP_SEG_SIZE} (or @code{INIT_HEAP_SIZE} if it is
smaller than @code{HEAP_SEG_SIZE}).
@item ERROR: Rogue pointer in Heap.
See above under machine crashes.
@item Newlines don't appear correctly in output files.
Check file mode (define OPEN_@dots{} in @file{Init.scm}
@item Spaces or control characters appear in symbol names
Check character defines in @file{scmfig.h}.
@item Negative numbers turn positive.
Check SRS in @file{scmfig.h}.
@item VMS: Couldn't unwind stack
@itemx VAX: botched longjmp
@code{#define CHEAP_CONTIUATIONS} in @file{scmfig.h}.
@item Sparc(SUN-4) heap is growing out of control
You are experiencing a GC problem peculiar to the Sparc.  The problem is
that SCM doesn't know how to clear register windows.  Every location
which is not reused still gets marked at GC time.  This causes lots of
stuff which should be collected to not be.  This will be a problem with
any @emph{conservative} GC until we find what instruction will clear the
register windows.  This problem is exacerbated by using lots of
call-with-current-continuations.
@end table

@node Reporting Problems,  , Testing, Installing SCM
@section Reporting Problems

@noindent
Reported problems and solutions are grouped under Compiling, Linking,
Running, and Testing.  If you don't find your problem listed there, you
can send a bug report to @code{jaffer@@ai.mit.edu} or
@code{bug-scm@@scrg.cs.tcd.ie}.  The bug report should include:

@enumerate
@item
The version of SCM (printed when SCM is invoked with no arguments).
@item
The type of computer you are using.
@item
The name and version of your computer's operating system.
@item
The values of the environment variables @code{SCM_INIT_PATH} and
@code{SCHEME_LIBRARY_PATH}.
@item
The name and version of your C compiler.
@item
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.
@end enumerate

@node Standard Facilities, Packages, Installing SCM, Top
@chapter Standard Facilities

@menu
* Standards Compliance::        Links to sections in [R4RS] and [SLIB]
* System Interface::            Like how to exit
* Internal State::              GC, errors, and diagnostics
* Miscellaneous Procedures::    
* Time::                        Both real time and processor time
* Interrupts::                  and exceptions
* Process Synchronization::     Because interrupts are preemptive
* Files and Ports::             
* Soft Ports::                  Emulate I/O devices
* Syntax Extensions::           and how to Define New Syntax
* Low Level Syntactic Hooks::   
@end menu

@node Standards Compliance, System Interface, Standard Facilities, Standard Facilities
@section Standards Compliance

@noindent
Scm conforms to the
@ifset html
[IEEE],
@end ifset
@cite{IEEE Standard 1178-1990.  IEEE Standard for the Scheme Programming
Language.}
@ifclear html
(@pxref{Bibliography}),
@end ifclear
and
@ifset html
[R4RS], <A HREF="r4rs_toc.html">
@end ifset
@cite{Revised(4) Report on the Algorithmic Language Scheme}.
@ifset html
</A>
@end ifset
@ifinfo
@ref{Top, , , r4rs, Revised(4) Report on the Algorithmic Language
Scheme}.
@end ifinfo
All the required features of these specifications are supported.
Many of the optional features are supported as well.

@subheading Optionals of [R4RS] Supported by SCM

@table @asis
@item two clause @code{if}: @code{(if <test> <consequent>)}
@xref{Conditionals, , , r4rs, Revised(4) Scheme}.
@item @code{let*}
@itemx named @code{let}
@xref{Binding constructs, , , r4rs, Revised(4) Scheme}.
@item @code{do}
@xref{Iteration, , , r4rs, Revised(4) Scheme}.
@item All varieties of @code{define}
@xref{Definitions, , , r4rs, Revised(4) Scheme}.
@item @code{list-tail}
@xref{Pairs and lists, , , r4rs, Revised(4) Scheme}.
@item @code{string-copy}
@itemx @code{string-fill!}
@xref{Strings, , , r4rs, Revised(4) Scheme}.
@item @code{make-vector} of two arguments
@itemx @code{vector-fill!}
@xref{Vectors, , , r4rs, Revised(4) Scheme}.
@item @code{apply} of more than 2 arguments
@xref{Control features, , , r4rs, Revised(4) Scheme}.
@item @code{-} and @code{/} of more than 2 arguments
@itemx @code{exp}
@itemx @code{log}
@itemx @code{sin}
@itemx @code{cos}
@itemx @code{tan}
@itemx @code{asin}
@itemx @code{acos}
@itemx @code{atan}
@itemx @code{sqrt}
@itemx @code{expt}
@itemx @code{make-rectangular}
@itemx @code{make-polar}
@itemx @code{real-part}
@itemx @code{imag-part}
@itemx @code{magnitude}
@itemx @code{angle}
@itemx @code{exact->inexact}
@itemx @code{inexact->exact}
@xref{Numerical operations, , , r4rs, Revised(4) Scheme}.
@item @code{delay}
@itemx @code{force}
@xref{Control features, , , r4rs, Revised(4) Scheme}.
@itemx @code{with-input-from-file}
@itemx @code{with-output-to-file}
@xref{Ports, , , r4rs, Revised(4) Scheme}.
@itemx @code{char-ready?}
@xref{Input, , , r4rs, Revised(4) Scheme}.
@itemx @code{transcript-on}
@itemx @code{transcript-off}
@xref{System interface, , , r4rs, Revised(4) Scheme}.
@end table

@subheading Optionals of [R4RS] not Supported by SCM

@table @asis
@item @code{numerator}
@itemx @code{denominator}
@itemx @code{rationalize}
@xref{Numerical operations, , , r4rs, Revised(4) Scheme}.
@item [R4RS] appendix Macros
@xref{Macros, , , r4rs, Revised(4) Scheme}.
@end table

@subheading [SLIB] Features of SCM and SCMLIT

@table @code
@item delay
@itemx full-continuation
@itemx ieee-p1178
@itemx object-hash
@itemx rev4-report
@itemx source
See SLIB file @file{Template.scm}.
@item current-time
@xref{Time, , , slib, SLIB}.
@item defmacro
@xref{Defmacro, , , slib, SLIB}.
@item dynamic-wind
@xref{Dynamic-Wind, , , slib, SLIB}.
@item eval
@xref{System, , , slib, SLIB}.
@item getenv
@itemx system
@xref{System Interface, , , slib, SLIB}.
@item hash
@xref{Hashing, , , slib, SLIB}.
@item logical
@xref{Bit-Twiddling, , , slib, SLIB}.
@item multiarg-apply
@xref{Multi-argument Apply, , , slib, SLIB}.
@item multiarg/and-
@xref{Multi-argument / and -, , , slib, SLIB}.
@item rev4-optional-procedures
@xref{Rev4 Optional Procedures, , , slib, SLIB}.
@item string-port
@xref{String Ports, , , slib, SLIB}.
@item tmpnam
@xref{Input/Output, , , slib, SLIB}.
@item transcript
@xref{Transcripts, , , slib, SLIB}.
@item vicinity
@xref{Vicinity, , , slib, SLIB}.
@item with-file
@xref{With-File, , , slib, SLIB}.
@end table

@subheading [SLIB] Features of SCM

@table @code
@item array
@xref{Arrays, , , slib, SLIB}.
@item array-for-each
@xref{Array Mapping, , , slib, SLIB}.
@item bignum
@itemx complex
@itemx inexact
@itemx rational
@itemx real
@xref{Require, , , slib, SLIB}.
@end table

@node System Interface, Internal State, Standards Compliance, Standard Facilities
@section System Interface

@noindent
For documentation of the procedures @code{getenv} and @code{system}
@xref{System Interface, , , slib, SLIB}.

@defun quit
@defunx quit n
@defunx exit
@defunx exit n
Aliases for @code{exit} (@pxref{System, exit, , slib, SLIB}).  On many
systems, SCM can also tail-call another program.  @xref{I/O-Extensions,
execp}.
@end defun

@defun vms-debug
If SCM is compiled under VMS these commands will invoke the editor or
debugger respectively.
@end defun

@defun ed filename
If SCM is compiled under VMS @code{ed} will invoke the editor with a
single the single argument @var{filename}.

@defunx ed arg1 @dots{}
Otherwise, the value of the environment variable @code{EDITOR} (or just
@code{ed} if it isn't defined) is invoked as a command with arguments
@var{arg1} @dots{}.
@end defun

@defun program-arguments
Returns a list of strings of the arguments scm was called with.
@end defun

@defun errno
@defunx errno n
With no argument returns the current value of the system variable
@code{errno}.  When given an argument, @code{errno} sets the system
variable @code{errno} to @var{n} and returns the previous value of
@code{errno}.  @code{(errno 0)} will clear outstanding errors.  This is
recommended after @code{try-load} returns @code{#f} since this occurs
when the file could not be opened.
@end defun

@defun perror string
Prints on standard error output the argument @var{string}, a colon,
followed by a space, the error message corresponding to the current
value of @code{errno} and a newline.  The value returned is unspecified.
@end defun

@node Internal State, Miscellaneous Procedures, System Interface, Standard Facilities
@section Internal State

@defvar errobj
If 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 @var{errobj} is the offending object
if appropriate.  @var{errobj} is @emph{not} set from calls to the
procedure @code{error}.
@end defvar

@defun error arg1 arg2 arg3 @dots{}
Alias for @ref{System, error, , slib, SLIB}.  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
@file{Init.scm}; You change it to suit you.
@end defun

@defun abort
Resumes the top level Read-Eval-Print loop.
@end defun

@defun verbose n
Controls how much monitoring information is printed.
If @var{n} is:

@table @asis
@item 0
no prompt or information is printed.
@item >= 1
a prompt is printed.
@item >= 2
the CPU time is printed after each top level form evaluated.
@item >= 3
messages about heap growth are printed.
@item >= 4
garbage collection (@pxref{Garbage Collection}) messages are printed.
@item >= 5
a warning will be printed for each top-level symbol which is defined
more than one time.
@end table
@end defun

@defun gc
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.
@end defun

@defun room
@defunx room #t
Prints out statistics about SCM's current use of storage.  @code{(room #t)}
also gives the hexadecimal heap segment and stack bounds.
@end defun

@defvr Constant *scm-version*
Contains the version string (e.g. @file{4e2}) of SCM.
@end defvr

@noindent
For other configuration constants and procedures @xref{Configuration, ,
, slib, SLIB}.

@node Miscellaneous Procedures, Time, Internal State, Standard Facilities
@section Miscellaneous Procedures

@defun try-load filename
If the string @var{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 @code{#t}.  If not,
try-load returns @code{#f}.  The try-load procedure does not affect the
values returned by @code{current-input-port} and
@code{current-output-port}.
@end defun

@defvar *load-pathname*
Is set to the pathname given as argument to @code{load},
@code{try-load}, and @code{dyn:link} (@pxref{Compiling And Linking}).
@code{*load-pathname*} is used to compute the value of @ref{Vicinity,
program-vicinity, , slib, SLIB}.
@end defvar

@defun line-number
Returns the current line number of the file currently being loaded.
@end defun

@defun eval obj
Alias for @ref{System, eval, , slib, SLIB}.
@end defun

@defun eval-string str
Returns the result of reading an expression from @var{str} and
evaluating it.  @code{eval-string} does not change
@code{*load-pathname*} or  @code{line-number}.
@end defun

@defun load-string str
Reads and evaluates all the expressions from @var{str}.  As with
@code{load}, the value returned is unspecified.  @code{eval-string} does
not change @code{*load-pathname*} or @code{line-number}.
@end defun

@defun vector-set-length! object length
Change the length of string, vector, bit-vector, or uniform-array
@var{object} to @var{length}.  If this shortens @var{object} then the
remaining contents are lost.  If it enlarges @var{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.
@end defun

@defun copy-tree obj
@xref{Tree Operations, copy-tree, , slib, SLIB}.  This extends the SLIB
version by also copying vectors.
@end defun

@defun 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.
@end defun

@defun terms
This command displays the GNU General Public License.
@end defun

@defun list-file filename
Displays the text contents of @var{filename}.
@end defun

@node Time, Interrupts, Miscellaneous Procedures, Standard Facilities
@section Time

@defvr Constant internal-time-units-per-second

Is the integer number of internal time units in a second.
@end defvr

@defun get-internal-run-time
Returns the integer run time in internal time units from an unspecified
starting time.  The difference of two calls to
@code{get-internal-run-time} divided by
@code{internal-time-units-per-second} will give elapsed run time in
seconds.
@end defun

@defun get-internal-real-time
Returns the integer time in internal time units from an unspecified
starting time.  The difference of two calls to
@code{get-internal-real-time} divided by
@code{interal-time-units-per-second} will give elapsed real time in
seconds.
@end defun

@defun current-time
Returns the time since 00:00:00 GMT, January 1, 1970, measured in
seconds.  @xref{Time, current-time, , slib, SLIB}.  @code{current-time} is
used in @ref{Time, , , slib, SLIB}.
@end defun

@node Interrupts, Process Synchronization, Time, Standard Facilities
@section Interrupts

@defun 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 @var{n} is 0, any ticks request is canceled.  Otherwise a
@code{ticks-interrupt} will be signaled @var{n} from the current time.
@code{ticks} is supported if SCM is compiled with the @code{ticks} flag
defined.
@end defun

@deffn {Callback procedure} ticks-interrupt @dots{}
Establishes a response for tick interrupts.  Another tick interrupt will
not occur unless @code{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.
@end deffn

@defun alarm secs
Returns the number of seconds remaining till the next alarm interrupt.
If @var{secs} is 0, any alarm request is canceled.  Otherwise an
@code{alarm-interrupt} will be signaled @var{secs} from the current
time.  ALARM is not supported on all systems.
@end defun

@deffn {Callback procedure} user-interrupt @dots{}
@deffnx {Callback procedure} alarm-interrupt @dots{}
Establishes a response for @code{SIGINT} (control-C interrupt) and
@code{SIGALRM} interrupts.  Program execution will resume if the handler
returns.  This procedure should @code{(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 @code{system} and
@code{ed} procedures.

To unestablish a response for an interrupt set the handler symbol to
@code{#f}.  For instance, @code{(set! user-interrupt #f)}.
@end deffn

@deffn {Callback procedure} out-of-storage @dots{}
@deffnx {Callback procedure} could-not-open @dots{}
@deffnx {Callback procedure} end-of-program @dots{}
@deffnx {Callback procedure} hang-up @dots{}
@deffnx {Callback procedure} arithmetic-error @dots{}
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 @var{hang-up}
then @var{end-of-program} (if defined) will be called.

To unestablish a response for an error set the handler symbol to
@code{#f}.  For instance, @code{(set! could-not-open #f)}.
@end deffn

@node Process Synchronization, Files and Ports, Interrupts, Standard Facilities
@section Process Synchronization

@defun make-arbiter name

Returns an object of type arbiter and name @var{name}.  Its state is
initially unlocked.
@end defun

@defun try-arbiter arbiter

Returns @code{#t} and locks @var{arbiter} if @var{arbiter} was unlocked.
Otherwise, returns @code{#f}.
@end defun

@defun release-arbiter arbiter

Returns @code{#t} and unlocks @var{arbiter} if @var{arbiter} was locked.
Otherwise, returns @code{#f}.
@end defun

@node Files and Ports, Soft Ports, Process Synchronization, Standard Facilities
@section Files and Ports

@noindent
These procedures generalize and extend the standard capabilities in
@ref{Ports, , ,r4rs, Revised(4) Scheme}.

@defun open-file string modes
Returns a port capable of receiving or delivering characters as
specified by the @var{modes} string.  If a file cannot be opened
@code{#f} is returned.
@end defun

@defvr Constant open_read
@defvrx Constant open_write
@defvrx Constant open_both
Contain modes strings specifying that a file is to be opened for
reading, writing, and both reading and writing respectively.
@end defvr

@defun _ionbf modestr
Returns a version of modestr which when open-file is called with it as
the second argument will return an unbuffered port.  A non-file
input-port must be unbuffered in order for char-ready? to work correctly
on it.  The initial value of (current-input-port) is unbuffered if the
platform supports it.
@end defun

@defun close-port port
Closes @var{port}.  The same as close-input-port and close-output-port.
@end defun

@defun open-io-file filename
@defunx close-io-port port
These functions are analogous to the standard scheme file functions.
The ports are open to @var{filename} in read/write mode.  Both input and
output functions can be used with io-ports.  An end of file must be read
or a file-set-position done on the port between a read operation and a
write operation or vice-versa.
@end defun

@defun current-error-port
Returns the current port to which diagnostic output is directed.
@end defun

@defun with-error-to-file string thunk
@var{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 @var{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 @var{thunk}.
@end defun

@defun with-input-from-port port thunk
@defunx with-output-to-port port thunk
@defunx 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.
@end defun


@node Soft Ports, Syntax Extensions, Files and Ports, Standard Facilities
@section Soft Ports

@noindent
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters.  It allows emulation of I/O ports.

@defun make-soft-port vector modes
Returns a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{Files and Ports,
open-file}).  @var{vector} must be a vector of length 6.  Its components
are as follows:

@enumerate 0
@item
procedure accepting one character for output
@item
procedure accepting a string for output
@item
thunk for flushing output
@item
thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate

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 @code{#f} if there is no useful
operation for them to perform.

If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,
eof-object?, ,r4rs, Revised(4) Scheme}) it indicates that the port has
reached end-of-file.  For example:

@example
(define stdout (current-output-port))
(define p (make-soft-port
           (vector
            (lambda (c) (write c stdout))
            (lambda (s) (display s stdout))
            (lambda () (display "." stdout))
            (lambda () (char-upcase (read-char)))
            (lambda () (display "@@" stdout)))
           "rw"))

(write p p) @result{} #<input-output-soft#\space45d10#\>
@end example
@end defun

@node Syntax Extensions, Low Level Syntactic Hooks, Soft Ports, Standard Facilities
@section Syntax Extensions

@deffn {Read syntax} #. expression
Is read as the object resulting from the evaluation of @var{expression}.
This substitution occurs even inside quoted structure.

In order to allow compiled code to work with @code{#.} it is good
practice to define those symbols used inside of @var{expression} with
@code{#.(define @dots{})}.  For example:

@example
#.(define foo 9)                        @result{} #<unspecified>
'(#.foo #.(+ foo foo))                  @result{} (9 18)
@end example
@end deffn

@deffn {Read syntax} #+ feature form
If feature is @code{provided?} (by @code{*features*}) then @var{form} is
read as a scheme expression.  If not, then @var{form} is treated as
whitespace.

Feature is a boolean expression composed of symbols and @code{and},
@code{or}, and @code{not} of boolean expressions.

For more information on @code{provided?} and @code{*features*},
@xref{Require, , , slib, SLIB}.
@end deffn

@deffn {Read syntax} #- feature form
is equivalent to @code{#+(not feature) expression}.
@end deffn

@deffn {Read syntax} #' form
is equivalent to @var{form} (for compatibility with common-lisp).
@end deffn

@deffn {Read syntax} #| any thing |#
Is a balanced comment.  Everything up to the matching @code{|#} is
ignored by the @code{read}.  Nested @code{#|@dots{}|#} can occur inside
@var{any thing}.
@end deffn

@deffn {Read syntax} #! any thing
On the first line of a file will be ignored when loaded by SCM.  This
makes SCM files usable as POSIX shell scripts if the first line is:

@example
#!/usr/local/bin/scm
@end example

When such a file is invoked it executes /usr/local/bin/scm with the
name of this file as the first argument.  The following shell script
will print factorial of its argument:
@example
#!/usr/local/bin/scm
;;; -*-scheme-*- tells emacs this is a scheme file.
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(display (fact (string->number (caddr (program-arguments)))))
(newline)
(quit)
@end example

This technique has some drawbacks:
@itemize @bullet
@item
Some Unixes limit the length of the @samp{#!} interpreter line to the
size of an object file header, which can be as small as 32 bytes.
@item
A full, explicit pathname must be specified, perhaps requiring more than
32 bytes and making scripts vulnerable to programs being moved.
@end itemize

The following approach solves both problems -- at the expense of
slightly slower startup.  @code{type;} should appear on every line to be
executed by the shell.  These lines do not have the length restriction
mentioned above.  Also, @code{/bin/sh} searches the directories listed
in the `PATH' environment variable for @samp{scm}, eliminating the need
to know absolute locations in order to invoke a program.
@example
#!/bin/sh
type;exec scm $0 $*
;;; -*-scheme-*- tells emacs this is a scheme file.
(define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
(display (fact (string->number (caddr (program-arguments)))))
(newline)
(quit)
@end example
@end deffn

@defspec defined? symbol
Equivalent to @code{#t} if @var{symbol} is a syntactic keyword (such as
@code{if}) or a symbol with a value in the top level environment
(@pxref{Variables and regions, , ,r4rs, Revised(4) Scheme}).  Otherwise
equivalent to @code{#f}.
@end defspec

@defspec defvar identifier initial-value
If @var{identifier} is unbound in the top level environment, then
@var{identifier} is @code{define}d to the result of evaluating the form
@var{initial-value} as if the @code{defvar} form were instead the form
@code{(define identifier initial-value)} .  If @var{identifier} already
has a value, then @var{initial-value} is @emph{not} evaluated and
@var{identifier}'s value is not changed.
@end defspec

@noindent
SCM also supports the following constructs from Common Lisp:
@code{defmacro}, @code{macroexpand}, @code{macroexpand-1}, and
@code{gentemp}.  @xref{Defmacro, , , slib, SLIB}.


@node Low Level Syntactic Hooks,  , Syntax Extensions, Standard Facilities
@section Low Level Syntactic Hooks

@deffn {Callback procedure} read:sharp c port
If a @key{#} followed by a character (for a non-standard syntax) is
encountered by @code{read}, @code{read} will call the value of the
symbol @code{read:sharp} with arguments the character and the port being
read from.  The value returned by this function will be the value of
@code{read} for this expression unless the function returns
@code{#<unspecified>} in which case the expression will be treated as
whitespace.  @code{#<unspecified>} is the value returned by the
expression @code{(if #f #f)}.

@emph{Note:} When adding new @key{#} syntaxes, have your code save the
previous value of @code{read:sharp} when defining it.  Call this saved
value if an invocation's syntax is not recognized.  This will allow
@code{#+}, @code{#-}, @code{#!}, and @ref{Uniform Array}s to still be
supported (as they use @code{read:sharp}).
@end deffn

@defun procedure->syntax proc
Returns a @dfn{macro} which, when a symbol defined to this value appears
as the first symbol in an expression, returns the result of applying
@var{proc} to the expression and the environment.
@end defun

@defun procedure->macro proc
@defunx procedure->memoizing-macro proc
Returns a @dfn{macro} which, when a symbol defined to this value appears
as the first symbol in an expression, evaluates the result of applying
@var{proc} to the expression and the environment.  The value returned
from @var{proc} which has been passed to
@code{PROCEDURE->MEMOIZING-MACRO} replaces the form passed to
@var{proc}.  For example:

@example
(define trace
  (procedure->macro
   (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))

(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example

An @dfn{environment} is a list of @dfn{environment frames}.  There are 2
types of environment frames:

@table @code
@item ((lambda (variable1 @dots{}) @dots{}) value1 @dots{})
@itemx (let ((variable1 value1) (variable2 value2) @dots{}) @dots{})
@itemx (letrec ((variable1 value1)  @dots{}) @dots{})
result in a single enviroment frame:
@example
((variable1 @dots{}) value1 @dots{})
@end example

@item (let ((variable1 value1)) @dots{})
@itemx (let* ((variable1 value1) @dots{}) @dots{})
result in an environment frame for each variable:
@example
(variable1 . value1) (variable2 .  value2) @dots{}
@end example
@end table
@end defun

@defspec @@apply procedure argument-list
Returns the result of applying procedure to argument-list.  (apply
procedure argument-list) will produce the same result.
@end defspec

@defspec @@call-with-current-continuation procedure)
Returns the result of applying procedure to the current continuation.
@code{(call-with-current-continuation @var{procedure})} will have the
same effect.
@end defspec


@node Packages, Guile Facilities, Standard Facilities, Top
@chapter Packages

@menu
* Compiling And Linking::       and Dynamic Linking
* Numeric::                     
* Arrays::                      As in APL
* I/O-Extensions::              'i/o-extensions
* Posix Extensions::            
* Regular Expression Pattern Matching::  'regex
* Line Editing::                
* Curses::                      Screen Control
* Sockets::                     Cruise the Net
@end menu

@node Compiling And Linking, Numeric, Packages, Packages
@section Compiling And Linking

@defun compile-file name1 name2 @dots{}
If the HOBBIT compiler is installed in the
@code{(implementation-vicinity)}, compiles the files @var{name1}
@var{name2} @dots{} to an object file name @var{name1}<object-suffix>,
where <object-suffix> is the object file suffix for your computer (for
instance, @file{.o}).  @var{name1} must be in the current directory.
@var{name2} @dots{} can be in other directories.
@end defun

@defun link-named-scm name module1 @dots{}
Creates a new SCM executable with name @var{name}.  @var{name} will include
the object modules @var{module1} @dots{} which can be produced with
compile-file.
@end defun

@noindent
If SCM has been compiled with @file{dynl.c} then the additional
properties of load and require (from [SLIB]) specified below are
supported.  The @code{require} forms are preferred.  The variable
@code{*catalog*} can be extended to define other requirable packages.
See @file{Link.scm} for details.

@defun load filename lib1 @dots{}
In addition to the [R4RS] requirement of loading Scheme expressions if
@var{filename} is a Scheme source file, @code{load} will also
dynamically load/link object files (produced by @code{compile-file}, for
instance).  The object-suffix need not be given to load.  For example,

@example
(load (in-vicinity (implementation-vicinity) "sc2"))
or (load (in-vicinity (implementation-vicinity) "sc2.o"))
or (require 'rev2-procedures)
or (require 'rev3-procedures)
@end example

will load/link @file{sc2.o} if it exists.

The @var{lib1} @dots{} pathnames are for additional libraries which may be
needed for object files not produced by the Hobbit compiler.  For
instance, crs is linked on Linux by

@example
(load (in-vicinity (implementation-vicinity) "crs.o")
      (usr:lib "ncurses") (usr:lib "c"))
or (require 'curses)
@end example

Turtlegr graphics library is linked by:

@example
(load (in-vicinity (implementation-vicinity) "turtlegr")
      (usr:lib "X11") (usr:lib "c") (usr:lib "m"))
or (require 'turtle-graphics)
@end example

And the string regular expression (@pxref{Regular Expression Pattern
Matching}) package is linked by:

@example
(load (in-vicinity (implementation-vicinity) "rgx") (usr:lib "c"))
@end example
or
@example
(require 'regex)
@end example
@end defun

@defun require 'db
@defunx require 'wb
Either form will dynamically load the WB database system from the
wb:vicinity (@file{../wb/}) specified in @file{Link.scm}.  See
@file{scm/ANNOUNCE} for ftp sites where WB is available.
@end defun

@noindent
The following functions comprise the low-level Scheme interface to
dynamic linking.  See the file @file{Link.scm} in the SCM distribution
for an example of their use.

@defun dyn:link filename
@var{filename} should be a string naming an @dfn{object} or
@dfn{archive} file, the result of C-compiling.  The @code{dyn:link}
procedure links and loads @var{filename} into the current SCM session.
If successfull, @code{dyn:link} returns a @dfn{link-token} suitable for
passing as the second argument to @code{dyn:call}.  If not successful,
@code{#f} is returned.
@end defun

@defun dyn:call name link-token
@var{link-token} should be the value returned by a call to
@code{dyn:link}.  @var{name} should be the name of C function of no
arguments defined in the file named @var{filename} which was succesfully
@code{dyn:link}ed in the current SCM session.  The @code{dyn:call}
procedure calls the C function corresponding to @var{name}.  If
successful, @code{dyn:call} returns @code{#t}; If not successful,
@code{#f} is returned.

@code{dyn:call} is used to call the @dfn{init_@dots{}} function after
loading SCM object files.  The init_@dots{} function then makes the
identifiers defined in the file accessible as Scheme procedures.
@end defun

@defun dyn:unlink link-token
@var{link-token} should be the value returned by a call to
@code{dyn:link}.  The @code{dyn:unlink} procedure removes the previously
loaded file from the current SCM session.  If successful,
@code{dyn:unlink} returns @code{#t}; If not successful, @code{#f} is
returned.
@end defun

@defun usr:lib lib
Returns the pathname of the C library named lib.  For example:
@code{(usr:lib "m")} could return @code{"/usr/lib/libm.a"}, the path of
the C math library.
@end defun

@node Numeric, Arrays, Compiling And Linking, Packages
@section Numeric

@defvr Constant most-positive-fixnum
The immediate integer closest to positive infinity.
@xref{Configuration, , , slib, SLIB}.
@end defvr

@defvr Constant most-negative-fixnum
The immediate integer closest to negative infinity.
@end defvr

@noindent
These procedures augment the standard capabilities in @ref{Numerical
operations, , ,r4rs, Revised(4) Scheme}.

@defun sinh z
@defunx cosh z
@defunx tanh z
Return the hyperbolic sine, cosine, and tangent of @var{z}
@end defun

@defun asinh z
@defunx acosh z
@defunx atanh z
Return the inverse hyperbolic sine, cosine, and tangent of @var{z}
@end defun

@defun $sqrt x
@defunx $abs x
@defunx $exp x
@defunx $log x
@defunx $sin x
@defunx $cos x
@defunx $tan x
@defunx $asin x
@defunx $acos x
@defunx $atan x

@defunx $sinh x
@defunx $cosh x
@defunx $tanh x
@defunx $asinh x
@defunx $acosh x
@defunx $atanh x
Real-only versions of these popular functions.  The argument @var{x}
must be a real number.  It is an error if the value which should be
returned by a call to these procedures is @emph{not} real.
@end defun

@defun $atan2 y x
Computes @code{(angle (make-rectangular x y))} for real numbers @var{y}
and @var{x}.
@end defun

@defun $expt x1 x2
Returns real number @var{x1} raised to the real power @var{x2}.  It is
an error if the value which should be returned by a call to @code{$expt}
is not real.
@end defun

@node Arrays, I/O-Extensions, Numeric, Packages
@section Arrays

@menu
* Conventional Arrays::         
* Array Mapping::               
* Uniform Array::               
* Bit Vectors::                 
@end menu

@node Conventional Arrays, Array Mapping, Arrays, Arrays
@subsection Conventional Arrays

@dfn{Arrays} read and write as a @code{#} followed by the @dfn{rank}
(number of dimensions) followed by 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.
@example
(make-array 'ho 3 3) @result{}
#2((ho ho ho) (ho ho ho) (ho ho ho))
@end example

Unshared conventional (not uniform) 0-based arrays of rank 1 (dimension)
are equivalent to (and can't be distinguished from) vectors.
@example
(make-array 'ho 3) @result{} (ho ho ho)
@end example

When constructing an array, @var{bound} is either an inclusive range of
indices expressed as a two element list, or an upper bound expressed
as a single integer.  So
@example
(make-array 'foo 3 3) @equiv{} (make-array 'foo '(0 2) '(0 2))
@end example

@defun array? obj
Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.
@end defun

@defun make-array initial-value bound1 bound2 @dots{}
Creates and returns an array that has as many dimensions as there are
@var{bound}s and fills it with @var{initial-value}.
@end defun

@defun array-ref array index1 index2 @dots{}
Returns the element at the @code{(index1, index2)} element in @var{array}.
@end defun

@defun array-in-bounds? array index1 index2 @dots{}
Returns @code{#t} if its arguments would be acceptable to array-ref.
@end defun

@defun array-set! array new-value index1 index2 @dots{}
Sets the element at the @code{(index1, index2)} element in @var{array} to
@var{new-value}.  The value returned by array-set! is unspecified.
@end defun

@defun make-shared-array array mapper bound1 bound2 @dots{}
@code{make-shared-array} can be used to create shared subarrays of other
arrays.  The @var{mapper} is a function that translates coordinates in
the new array into coordinates in the old array.  A @var{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:
@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) @result{} foo
(define freds-center
  (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))
(array-ref freds-center 0 0) @result{} foo
@end example
@end defun

@defun transpose-array array dim0 dim1 @dots{}
Returns an array sharing contents with @var{array}, but with dimensions
arranged in a different order.  There must be one @var{dim} argument for
each dimension of @var{array}.  @var{dim0}, @var{dim1}, @dots{} 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 @var{dim0}, @var{dim1}, @dots{} correspond to dimensions
in the array to be returned, their positions in the argument list to
dimensions of @var{array}.  Several @var{dim}s may have the same value,
in which case the returned array will have smaller rank than
@var{array}.

examples:
@example
(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}
                #2((a 4) (b 5) (c 6))
@end example
@end defun

@defun enclose-array array dim0 dim1 @dots{}
@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than
the rank of @var{array}.  @var{enclose-array} returns an array
resembling an array of shared arrays.  The dimensions of each shared
array are the same as the @var{dim}th 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 @var{dim}.

An enclosed array is not a general Scheme array.  Its elements may not
be set using @code{array-set!}.  Two references to the same element of
an enclosed array will be @code{equal?} but will not in general be
@code{eq?}.  The value returned by @var{array-prototype} when given an
enclosed array is unspecified.

examples:
@example
(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}
   #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>

(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}
   #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>
@end example
@end defun

@defun array-shape array
Returns a list of inclusive bounds of integers.
@example
(array-shape (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) (0 4))
@end example
@end defun

@defun array-dimensions array
@code{Array-dimensions} is similar to @code{array-shape} but replaces
elements with a @code{0} minimum with one greater than the maximum. So:
@example
(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)
@end example
@end defun

@defun array-rank obj
Returns the number of dimensions of @var{obj}.  If @var{obj} is not an
array, @code{0} is returned.
@end defun

@defun array->list array
Returns a list consisting of all the elements, in order, of @var{array}.
@end defun

@defun array-copy! source destination
Copies every element from vector or array @var{source} to the
corresponding element of @var{destination}.  @var{destination} must have
the same rank as @var{source}, and be at least as large in each
dimension.  The order is unspecified.
@end defun

@defun serial-array-copy! source destination
Same as @code{array-copy!} but guaranteed to copy in row-major order.
@end defun

@defun array-fill! array fill
Stores @var{fill} in every element of @var{array}.  The value returned
is unspecified.
@end defun

@defun array-equal? array0 array1 @dots{}
Returns @code{#t} iff all arguments are arrays with the same shape, the
same type, and have corresponding elements which are either
@code{equal?}  or @code{array-equal?}.  This function differs from
@code{equal?} in that a one dimensional shared array may be
@var{array-equal?} but not @var{equal?} to a vector or uniform vector.
@end defun

@defun array-contents array
@defunx array-contents array strict
If @var{array} may be @dfn{unrolled} into a one dimensional shared array
without changing their order (last subscript changing fastest), then
@code{array-contents} returns that shared array, otherwise it returns
@code{#f}.  All arrays made by @var{make-array} and
@var{make-uniform-array} may be unrolled, some arrays made by
@var{make-shared-array} may not be.

If the optional argument @var{strict} is provided, a shared array will
be returned only if its elements are stored internally contiguous in
memory.
@end defun

@node Array Mapping, Uniform Array, Conventional Arrays, Arrays
@subsection Array Mapping

@defun array-map! array0 proc array1 @dots{}
@var{array1}, @dots{} must have the same number of dimensions as
@var{array0} and have a range for each index which includes the range
for the corresponding index in @var{array0}.  @var{proc} is applied to
each tuple of elements of @var{array1} @dots{} and the result is stored
as the corresponding element in @var{array0}.  The value returned is
unspecified.  The order of application is unspecified.
@end defun

@defun serial-array-map! array0 proc array1 @dots{}
Same as @var{array-map!}, but guaranteed to apply @var{proc} in
row-major order.
@end defun

@defun array-for-each proc array0 @dots{}
@var{proc} is applied to each tuple of elements of @var{array0} @dots{}
in row-major order.  The value returned is unspecified.
@end defun

@defun array-index-map! array proc
applies @var{proc} to the indices of each element of @var{array} in
turn, storing the result in the corresponding element.  The value
returned and the order of application are unspecified.

One can implement @var{array-indexes} as
@example
(define (array-indexes array)
    (let ((ra (apply make-array #f (array-shape array))))
      (array-index-map! ra (lambda x x))
      ra))
@end example
Another example:
@example
(define (apl:index-generator n)
    (let ((v (make-uniform-vector n 1)))
      (array-index-map! v (lambda (i) i))
      v))
@end example
@end defun

@node Uniform Array, Bit Vectors, Array Mapping, Arrays
@subsection Uniform Array

@noindent
@dfn{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.

@noindent
@var{prototype} arguments in the following procedures are interpreted
according to the table:

@example
prototype       type                            printing character

#t              boolean (bit-vector)                    b
#\a             char (string)                           a
integer >0      unsigned integer                        u
integer <0      signed integer                          e
1.0             float (single precision)                s
1/3             double (double precision float)         i
+i              complex (double precision)              c
()              conventional vector
@end example

@noindent
Unshared uniform character 0-based arrays of rank 1 (dimension)
are equivalent to (and can't be distinguished from) strings.
@example
(make-uniform-array #\a 3) @result{} "$q2"
@end example

@noindent
Unshared uniform boolean 0-based arrays of rank 1 (dimension) are
equivalent to (and can't be distinguished from) @ref{Bit Vectors,
bit-vectors}.
@example
(make-uniform-array #t 3) @result{} #*000
@equiv{}
#b(#f #f #f) @result{} #*000
@equiv{}
#1b(#f #f #f) @result{} #*000
@end example

@noindent
Other uniform vectors are written in a form similar to that of vectors,
except that a single character from the above table is put between
@code{#} and @code{(}.  For example, @code{'#e(3 5 9)} returns a uniform
vector of signed integers.

@defun array? obj prototype
Returns @code{#t} if the @var{obj} is an array of type corresponding to
@var{prototype}, and @code{#f} if not.
@end defun

@defun make-uniform-array prototype bound1 bound2 @dots{}
Creates and returns a uniform array of type corresponding to
@var{prototype} that has as many dimensions as there are @var{bound}s
and fills it with @var{prototype}.
@end defun

@defun array-prototype array
Returns an object that would produce an array of the same type as
@var{array}, if used as the @var{prototype} for
@code{make-uniform-array}.
@end defun

@defun list->uniform-array rank prot lst
@defunx list->uniform-vector prot lst
Returns a uniform array of the type indicated by prototype @var{prot}
with elements the same as those of @var{lst}.  Elements must be of the
appropriate type, no coercions are done.
@end defun

@defun uniform-vector-fill! uve fill
Stores @var{fill} in every element of @var{uve}.  The value returned is
unspecified.
@end defun

@defun uniform-vector-length uve
Returns the number of elements in @var{uve}.
@end defun

@defun dimensions->uniform-array dims prototype fill
@defunx dimensions->uniform-array dims prototype
@defunx make-uniform-vector length prototype fill
@defunx make-uniform-vector length prototype
Creates and returns a uniform array or vector of type corresponding to
@var{prototype} with dimensions @var{dims} or length @var{length}.  If
the @var{fill} argument is supplied, the returned array is filled with
this value.
@end defun

@defun uniform-array-read! ura
@defunx uniform-array-read! ura port
@defunx uniform-vector-read! uve
@defunx uniform-vector-read! uve port
Attempts to read all elements of @var{ura}, in lexicographic order, as
binary objects from @var{port}.  If an end of file is encountered during
uniform-array-read! the objects up to that point only are put into @var{ura}
(starting at the beginning) and the remainder of the array is
unchanged.

@code{uniform-array-read!} returns the number of objects read.
@var{port} may be omitted, in which case it defaults to the value
returned by @code{(current-input-port)}.
@end defun

@defun uniform-array-write ura
@defunx uniform-array-write ura port
@defunx uniform-vector-write uve
@defunx uniform-vector-write uve port
Writes all elements of @var{ura} as binary objects to @var{port}. The
number of of objects actually written is returned. @var{port} may be
omitted, in which case it defaults to the value returned by
@code{(current-output-port)}.
@end defun

@node Bit Vectors,  , Uniform Array, Arrays
@subsection Bit Vectors

@noindent
Bit vectors can be written and read as a sequence of @code{0}s and
@code{1}s prefixed by @code{#*}.

@example
#b(#f #f #f #t #f #t #f) @result{} #*0001010
@end example

@noindent
Some of these operations will eventually be generalized to other
uniform-arrays.

@defun bit-count bool bv
Returns the number occurrences of @var{bool} in @var{bv}.
@end defun

@defun bit-position bool bv k
Returns the minimum index of an occurrence of @var{bool} in @var{bv}
which is at least @var{k}.  If no @var{bool} occurs within the specified
range @code{#f} is returned.
@end defun

@defun bit-invert! bv
Modifies @var{bv} by replacing each element with its negation.
@end defun

@defun bit-set*! bv uve bool
If uve is a bit-vector @var{bv} and uve must be of the same length.  If
@var{bool} is @code{#t}, uve is OR'ed into @var{bv}; If @var{bool} is @code{#f}, the
inversion of uve is AND'ed into @var{bv}.

If uve is a unsigned integer vector all the elements of uve must be
between 0 and the @code{LENGTH} of @var{bv}.  The bits of @var{bv}
corresponding to the indexes in uve are set to @var{bool}.

The return value is unspecified.
@end defun

@defun bit-count* bv uve bool
Returns
@example
(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).
@end example
@var{bv} is not modified.
@end defun


@node I/O-Extensions, Posix Extensions, Arrays, Packages
@section I/O-Extensions

@noindent
If @code{'i/o-extensions} is provided (by linking in @file{ioext.o}),
@ref{Line I/O, , , slib, SLIB}, and the following functions are defined:

@defun isatty? port
Returns @code{#t} if @var{port} is input or output to a serial non-file device.
@end defun

@defun 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 @code{#f} is returned.
The elements of the returned vector are as follows:


@table @r
@item 0  st_dev
ID of device containing a directory entry for this file
@item 1  st_ino
Inode number
@item 2  st_mode
File type, attributes, and access control summary
@item 3  st_nlink
Number of links
@item 4  st_uid
User ID of file owner
@item 5  st_gid
Group ID of file group
@item 6  st_rdev
Device ID; this entry defined only for char or blk spec files
@item 7  st_size
File size (bytes)
@item 8  st_atime
Time of last access
@item 9  st_mtime
Last modification time
@item 10 st_ctime
Last file status change time
@end table
@end defun

@defun getpid
Returns the process ID of the current process.
@end defun

@defun file-position port
Returns the current position of the character in @var{port} which will
next be read or written.  If @var{port} is not open to a file the result
is unspecified.
@end defun

@defun file-set-position port integer
Sets the current position in @var{port} which will next be read or
written.  If @var{port} is not open to a file the action of
@code{file-set-position} is unspecified.  The result of
@code{file-set-position} is unspecified.
@end defun

@defun reopen-file filename modes port
Closes port @var{port} and reopens it with @var{filename} and
@var{modes}.  @code{reopen-file} returns @code{#t} if successful,
@code{#f} if not.
@end defun

@defun duplicate-port port modes
Creates and returns a @dfn{duplicate} port from @var{port}.  Duplicate
@emph{unbuffered} ports share one file position.  @var{modes} are as for
@ref{Files and Ports, open-file}.
@end defun

@defun redirect-port! from-port to-port
Closes @var{to-port} and makes @var{to-port} be a duplicate of
@var{from-port}.  @code{redirect-port!} returns @var{to-port} if
successful, @code{#f} if not.  If unsuccessful, @var{to-port} is not
closed.
@end defun

@defun opendir dirname
Returns a @dfn{directory} object corresponding to the file system
directory named @var{dirname}.  If unsuccessful, returns @code{#f}.
@end defun

@defun readdir dir
Returns the string name of the next entry from the directory @var{dir}.
If there are no more entries in the directory, @code{readdir} returns a
@code{#f}.
@end defun

@defun rewinddir dir
Reinitializes @var{dir} so that the next call to @code{readdir} with
@var{dir} will return the first entry in the directory again.
@end defun

@defun closedir dir
Closes @var{dir} and returns @code{#t}.  If @var{dir} is already
closed,, @code{closedir} returns a @code{#f}.
@end defun

@defun mkdir path mode
The @code{mkdir} function creates a new, empty directory whose name is
@var{path}.  The integer argument @var{mode} specifies the file
permissions for the new directory.  @xref{The Mode Bits for Access
Permission, , , libc, Gnu C Library}, for more information about this.

@code{mkdir} returns if successful, @code{#f} if not.
@end defun

@defun rmdir path
The @code{rmdir} function deletes the directory @var{path}.  The
directory must be empty before it can be removed.  @code{rmdir} returns
if successful, @code{#f} if not.
@end defun

@defun chdir filename
Changes the current directory to @var{filename}.  If @var{filename} does not
exist or is not a directory, @code{#f} is returned.  Otherwise, @code{#t} is
returned.
@end defun

@defun getcwd
The function @code{getcwd} returns a string containing the absolute file
name representing the current working directory.  If this string cannot
be obtained, @code{#f} is returned.
@end defun

@defun rename-file oldfilename newfilename
Renames the file specified by @var{oldfilename} to @var{newfilename}.
If the renaming is successful, @code{#t} is returned.  Otherwise,
@code{#f} is returned.
@end defun

@defun chmod file mode
The function @code{chmod} sets the access permission bits for the file
named by @var{file} to @var{mode}.  The @var{file} argument may be a
string containing the filename or a port open to the file.

@code{chmod} returns if successful, @code{#f} if not.
@end defun

@defun utime pathname acctime modtime
Sets the file times associated with the file named @var{pathname} to
have access time @var{acctime} and modification time @var{modtime}.
@code{utime} returns if successful, @code{#f} if not.
@end defun

@defun umask mode
The function @code{umask} sets the file creation mask of the current
process to @var{mask}, and returns the previous value of the file
creation mask.
@end defun

@defun fileno port
Returns the integer file descriptor associated with the port @var{port}.
If an error is detected, @code{#f} is returned.
@end defun

@defun access pathname how
Returns @code{#t} if the file named by @var{pathname} can be accessed in
the way specified by the @var{how} argument.  The @var{how} argument can
be the @code{logior} of the flags:

@enumerate 0
@item
File exists.
@item
File is executable.
@item
File is writable
@end enumerate
@enumerate 4
@item
File is readable
@end enumerate
@end defun

@defun execl command arg0 @dots{}
@defunx execlp command arg0 @dots{}
Transfers control to program @var{command} called with arguments
@var{arg0} @dots{}.  For @code{execl}, @var{command} must be an exact
pathname of an executable file.  @code{execlp} searches for
@var{command} in the list of directories specified by the environment
variable @var{PATH}.  The convention is that @var{arg0} is the same name
as @var{command}.

If successful, this procedure does not return.  Otherwise an error
message is printed and the integer @code{errno} is returned.

@defunx execv command arglist
@defunx execvp command arglist
Like @code{execl} and @code{execlp} except that the set of arguments to
@var{command} is @var{arglist}.
@end defun

@defun putenv string
adds or removes definitions from the @dfn{environment}. If the
@var{string} is of the form @samp{NAME=VALUE}, the definition is added
to the environment.  Otherwise, the @var{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 @code{=}.  System-defined environment variables are
invariably uppercase.

@code{Putenv} is used to set up the environment before calls to
@code{execl}, @code{execlp}, @code{execv}, @code{execvp}, @code{system},
or @code{open-pipe} (@pxref{I/O-Extensions, open-pipe}).

To access environment variables, use @code{getenv} (@pxref{System
Interface, getenv, , slib, SLIB}).
@end defun

@node Posix Extensions, Regular Expression Pattern Matching, I/O-Extensions, Packages
@section Posix Extensions

@noindent
If @code{'posix} is provided (by linking in @file{posix.o}), the
following functions are defined:

@defun open-pipe string modes
If the string @var{modes} contains an @key{r}, returns an input port
capable of delivering characters from the standard output of the system
command @var{string}.  Otherwise, returns an output port capable of
receiving characters which become the standard input of the system
command @var{string}.  If a pipe cannot be created @code{#f} is
returned.
@end defun

@defun open-input-pipe string
Returns an input port capable of delivering characters from the
standard output of the system command @var{string}.  If a pipe cannot be
created @code{#f} is returned.
@end defun

@defun open-output-pipe string
Returns an output port capable of receiving characters which become
the standard input of the system command @var{string}.  If a pipe cannot
be created @code{#f} is returned.
@end defun

@defun close-port pipe
Closes the @var{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.
@end defun

@defun pipe
Returns @code{(cons @var{rd} @var{wd})} where @var{rd} and @var{wd} are
the read and write (port) ends of a @dfn{pipe} respectively.
@end defun

@defun fork
Creates a copy of the process calling @code{fork}.  Both processes
return from @code{fork}, but the calling (@dfn{parent}) process's
@code{fork} returns the @dfn{child} process's ID whereas the child
process's @code{fork} returns 0.
@end defun

@noindent
For a discussion of @dfn{ID}s @xref{Process Persona, , , GNU C Library,
libc}.

@defun getppid
Returns the process ID of the parent of the current process.
For a process's own ID @xref{I/O-Extensions, getpid}.
@end defun

@defun getuid
Returns the real user ID of this process.
@end defun

@defun getgid
Returns the real group ID of this process.
@end defun

@defun getegid
Returns the effective group ID of this process.
@end defun

@defun geteuid
Returns the effective user ID of this process.
@end defun

@defun setuid id
Sets the real user ID of this process to @var{id}.
Returns @code{#t} if successful, @code{#f} if not.
@end defun

@defun setgid id
Sets the real group ID of this process to @var{id}.
Returns @code{#t} if successful, @code{#f} if not.
@end defun

@defun setegid id
Sets the effective group ID of this process to @var{id}.
Returns @code{#t} if successful, @code{#f} if not.
@end defun

@defun seteuid id
Sets the effective user ID of this process to @var{id}.
Returns @code{#t} if successful, @code{#f} if not.
@end defun

@defun kill pid sig
The @code{kill} function sends the signal @var{signum} to the process or
process group specified by @var{pid}.  Besides the signals listed in
@ref{Standard Signals, , ,libc , GNU C Library}, @var{signum} can also
have a value of zero to check the validity of the @var{pid}.

The @var{pid} specifies the process or process group to receive the
signal:

@table @asis
@item > 0
The process whose identifier is @var{pid}.

@item 0
All processes in the same process group as the sender.  The
sender itself does not receive the signal.

@item -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.

@item < -1
The process group whose identifier is @code{(abs @var{pid})}.
@end table

A process can send a signal to itself with @code{(kill (getpid)
@var{signum})}.  If @code{kill} is used by a process to send a signal to
itself, and the signal is not blocked, then @code{kill} delivers at
least one signal (which might be some other pending unblocked signal
instead of the signal @var{signum}) to that process before it returns.

The return value from @code{kill} is zero if the signal can be sent
successfully.  Otherwise, no signal is sent, and a value of @code{-1} is
returned.  If @var{pid} specifies sending a signal to several processes,
@code{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.
@end defun

@defun waitpid pid options

The @code{waitpid} function suspends execution of the current process
until a child as specified by the @var{pid} argument has exited, or until a
signal is deliverd whose action is to terminate the current process or
to call a signal handling function.  If a child as requested by @var{pid} has
already exited by the time of the call (a so-called @dfn{zombie}
process), the function returns immediately.  Any system resources used
by the child are freed.

The value of @var{pid} can be one of:

@table @asis
@item < -1
which means to wait for any child process whose process group ID is
equal to the absolute value of

@item -1
which means to wait for any child process whose process group ID is
equal to the @code{(abs @var{pid})}.

@item -1
which means to wait for any child process; this is the same behaviour
which wait exhibits.

@item 0
which means to wait for any child process whose process group ID is
equal to that of the calling process.

@item > 0
which means to wait for the child whose process ID is equal to the value
of @var{pid}.
@end table

The value of @var{options} is one of the following:

@enumerate 0
@item
Nothing special.

@item
(@code{WNOHANG}) which means to return immediately if no child is there
to be waited for.

@item
(@code{WUNTRACED}) which means to also return for children which are
stopped, and whose status has not been reported.

@item
Which means both of the above.
@end enumerate

The return value is normally the process ID of the child process whose
status is reported.  If the @code{WNOHANG} option was specified and no
child process is waiting to be noticed, the value is zero.  A value of
@code{#f} is returned in case of error and @code{errno} is set.  For
information about the @code{errno} codes @xref{Process Completion, , ,
GNU C Library, libc}.
@end defun

@defun uname
You can use the @code{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:

@enumerate 0
@item
The name of the operating system in use.
@item
The network name of this particular computer.
@item
The current release level of the operating system implementation.
@item
The current version level within the release of the operating system.
@item
Description of the type of hardware that is in use.

Some examples are @samp{"i386-ANYTHING"}, @samp{"m68k-hp"},
@samp{"sparc-sun"}, @samp{"m68k-sun"}, @samp{"m68k-sony"} and @samp{"mips-dec"}.
@end enumerate
@end defun

@defun getpw name
@defunx getpw uid
@defunx getpw
Returns a vector of information for the entry for @code{NAME},
@code{UID}, or the next entry if no argument is given.  The
information is:

@enumerate 0
@item
The user's login name.
@item
The encrypted password string.
@item
The user ID number.
@item
The user's default group ID number.
@item
A string typically containing the user's real name, and
possibly other information such as a phone number.
@item
The user's home directory, initial working directory, or @code{#f}, in
which case the interpretation is system-dependent.
@item
The user's default shell, the initial program run when the user logs in,
or @code{#f}, indicating that the system default should be used.
@end enumerate
@end defun

@defun setpwent #t
Rewinds the pw entry table back to the begining.

@defunx setpwent #f
@defunx setpwent
Closes the pw table.
@end defun


@defun getgr name
@defunx getgr uid
@defunx getgr
Returns a vector of information for the entry for @code{NAME},
@code{UID}, or the next entry if no argument is given.  The
information is:

@enumerate 0
@item
The name of the group.
@item
The encrypted password string.
@item
The group ID number.
@item
A list of (string) names of users in the group.
@end enumerate
@end defun

@defun setgrent #t
Rewinds the group entry table back to the begining.

@defunx setgrent #f
@defunx setgrent
Closes the group table.
@end defun

@defun getgroups
Returns a vector of all the supplementary group IDs of the process.
@end defun


@defun link oldname newname
The @code{link} function makes a new link to the existing file named by
@var{oldname}, under the new name @var{newname}.

@code{link} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun chown filename owner group
The @code{chown} function changes the owner of the file @var{filename}
to @var{owner}, and its group owner to @var{group}.

@code{chown} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun ttyname port
If port @var{port} is associated with a terminal device, returns a
string containing the file name of termainal device; otherwise
@code{#f}.
@end defun

@section Unix Extensions

@noindent
If @code{'unix} is provided (by linking in @file{unix.o}), the following
functions are defined:

@noindent
These @dfn{priveledged} and symbolic link functions are not in Posix:

@defun symlink oldname newname
The @code{symlink} function makes a symbolic link to @var{oldname} named
@var{newname}.

@code{symlink} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun readlink filename
Returns the value of the symbolic link @var{filename} or @code{#f} for
failure.
@end defun

@defun lstat filename
The @code{lstat} function is like @code{stat}, except that it does not
follow symbolic links.  If @var{filename} is the name of a symbolic
link, @code{lstat} returns information about the link itself; otherwise,
@code{lstat} works like @code{stat}.  @xref{I/O-Extensions}.
@end defun

@defun nice increment
Increment the priority of the current process by @var{increment}.
@code{chown} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun acct filename
When called with the name of an exisitng file as argument, accounting is
turned on, records for each terminating pro-cess are appended to
@var{filename} as it terminates.  An argument of @code{#f} causes
accounting to be turned off.

@code{acct} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun mknod filename mode dev
The @code{mknod} function makes a special file with name @var{filename}
and modes @var{mode} for device number @var{dev}.

@code{mknod} returns a value of @code{#t} if it is successful and
@code{#f} on failure.
@end defun

@defun sync
@code{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.
@end defun

@node Regular Expression Pattern Matching, Line Editing, Posix Extensions, Packages
@section Regular Expression Pattern Matching

These functions are defined in @file{rgx.c} using a POSIX or GNU
@dfn{regex} library.  If your computer does not support regex, a package
is available via ftp from
@file{prep.ai.mit.edu:/pub/gnu/regex-0.12.tar.gz}.  For a description of
regular expressions, @xref{syntax, , , regex, "regex" regular expression
matching library}.

@defun regcomp @var{pattern} [@var{flags}]
Compile a @dfn{regular expression}.  Return a compiled regular
expression, or an integer error code suitable as an argument to
@code{regerror}.

@var{flags} in @code{regcomp} is a string of option letters used to
control the compilation of the regular expression. The letters may
consist of:

@table @samp
@item n
newlines won't be matched by @code{.} or hat lists; ( @code{[^...]} )
@item i
ignore case.
@exdent only when compiled with @var{_GNU_SOURCE}:
@item 0
allows dot to match a null character.
@item f
enable GNU fastmaps.
@end table
@end defun

@defun regerror @var{errno}
Returns a string describing the integer @var{errno} returned when
@code{regcomp} fails.
@end defun

@defun regexec @var{re} @var{string}
Returns @code{#f} or a vector of integers.  These integers are in
doublets.  The first of each doublet is the index of @var{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
@var{string} of the end of that expression.  @code{#f} is returned if
the string does not match.
@end defun

@defun regmatch? @var{re} @var{string}
Returns @code{#t} if the @var{pattern} such that @var{regexp} = (regcomp
@var{pattern}) matches @var{string} as a POSIX extended regular
expressions.  Returns @code{#f} otherwise.
@end defun

@defun regsearch  @var{re} @var{string} [@var{start} [@var{len}]]
@defunx regsearchv @var{re} @var{string} [@var{start} [@var{len}]]
@defunx regmatch   @var{re} @var{string} [@var{start} [@var{len}]]
@defunx regmatchv  @var{re} @var{string} [@var{start} [@var{len}]]
@code{Regsearch} searches for the pattern within the string.

@code{Regmatch} anchors the pattern and begins matching it against
string.

@code{Regsearch} returns the character position where @var{re} starts,
or @code{#f} if not found.

@code{Regmatch} returns the number of characters matched, @code{#f} if
not matched.

@code{Regsearchv} and @code{regmatchv} return the match vector is
returned if @var{re} is found, @code{#f} otherwise.

@table @var
@item re
may be either:
@enumerate
@item
a compiled regular expression returned by @code{regcomp};
@item
a string representing a regular expression;
@item
a list of a string and a set of option letters.
@end enumerate
@item string
The string to be operated upon.
@item start
The character position at which to begin the search or match. If absent,
the default is zero.

@exdent @emph{Compiled _GNU_SOURCE and using GNU libregex only:}

When searching, if @var{start} is negative, the absolute value of
@var{start} will be used as the start location and reverse searching
will be performed.

@item len
The search is allowed to examine only the first @var{len} characters of
@var{string}. If absent, the entire string may be examined.
@end table
@end defun

@defun string-split  @var{re} @var{string}
@defunx string-splitv @var{re} @var{string}
@code{String-split} splits a string into substrings that are separated
by @var{re}, returning a vector of substrings.

@code{String-splitv} returns a vector of string positions that indicate
where the substrings are located.
@end defun

@defun string-edit  @var{re} @var{edit-spec} @var{string} [@var{count}]
Returns the edited string.

@table @var
@item edit-spec
Is a string used to replace occurances of @var{re}.  Backquoted integers
in the range of 1-9 may be used to insert subexpressions in @var{re}, as
in @code{sed}.
@item count
The number of substitutions for @code{string-edit} to perform.  If
@code{#t}, all occurances of @var{re} will be replaced.  The default is
to perform one substitution.
@end table
@end defun

@node Line Editing, Curses, Regular Expression Pattern Matching, Packages
@section Line Editing

@noindent
These procedures provide input line editing and recall.

@noindent
These functions are defined in @file{edline.c} and @file{Iedline.scm}
using the @dfn{editline} or GNU @dfn{readline} libraries available from:

@itemize @bullet
@item
@code{ftp.sys.toronto.edu:/pub/rc/editline.shar}
@item
@code{prep.ai.mit.edu:pub/gnu/readline-2.0.tar.gz}
@end itemize

@noindent
When @file{Iedline.scm} is loaded, if the current input port is the
default input port and the environment variable @var{EMACS} is not
defined, line-editing mode will be entered.

@defun default-input-port
Returns the initial @code{current-input-port} SCM was invoked with
(stdin).
@end defun

@defun default-output-port
Returns the initial @code{current-output-port} SCM was invoked with
(stdout).
@end defun

@defun make-edited-line-port
Returns an input/output port that allows command line editing and
retrieval of history.
@end defun

@defun line-editing
Returns the current edited line port or @code{#f}.

@defunx line-editing bool
If @var{bool} is false, exits line-editing mode and returns the previous
value of @code{(line-editing)}.  If @var{bool} is true, sets the current
input and output ports to an edited line port and returns the previous
value of @code{(line-editing)}.
@end defun

@node Curses, Sockets, Line Editing, Packages
@section Curses

@noindent
These functions are defined in @file{crs.c} using the @dfn{curses}
library.  Unless otherwise noted these routines return @code{#t} for
successful completion and @code{#f} for failure.

@defun initscr
Returns a port for a full screen window.  This routine must be called to
initialize curses.
@end defun

@defun endwin
A program should call @code{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 @ref{Window Manipulation,
refresh}.
@end defun

@menu
* Output Options Setting::      
* Terminal Mode Setting::       
* Window Manipulation::         
* Output::                      
* Input::                       
* Curses Miscellany::           
@end menu

@node Output Options Setting, Terminal Mode Setting, Curses, Curses
@subsection Output Options Setting

@noindent
These routines set options within curses that deal with output.  All
options are initially @code{#f}, unless otherwise stated.  It is not
necessary to turn these options off before calling @code{endwin}.

@defun clearok win bf
If enabled (@var{bf} is @code{#t}), the next call to @code{force-output}
or @code{refresh} with @var{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.
@end defun

@defun idlok win bf
If enabled (@var{bf} is @code{#t}), curses will consider using the
hardware ``insert/delete-line'' feature of terminals so equipped.  If
disabled (@var{bf} is @code{#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.
@end defun

@defun 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.
@end defun

@defun scrollok win bf
This option controls what happens when the cursor of window @var{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 (@var{bf} is @code{#f}), the cursor is left on the
bottom line at the location where the offending character was entered.
If enabled (@var{bf} is @code{#t}), @code{force-output} is called on the
window @var{win}, and then the physical terminal and window @var{win}
are scrolled up one line.

@emph{Note:} in order to get the physical scrolling effect on the
terminal, it is also necessary to call @code{idlok}.
@end defun

@defun 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.
@end defun

@node Terminal Mode Setting, Window Manipulation, Output Options Setting, Curses
@subsection Terminal Mode Setting

@noindent
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 @code{endwin}.  The routines in this section all return an
unspecified value.

@defun cbreak
@defunx nocbreak
These two routines put the terminal into and out of @code{CBREAK} mode,
respectively.  In @code{CBREAK} mode, characters typed by the user are
immediately available to the program and erase/kill character
processing is not performed.  When in @code{NOCBREAK} mode, the tty driver
will buffer characters typed until a @key{LFD} or @key{RET} is typed.
Interrupt and flowcontrol characters are unaffected by this mode.
Initially the terminal may or may not be in @code{CBREAK} mode, as it is
inherited, therefore, a program should call @code{cbreak} or @code{nocbreak}
explicitly.  Most interactive programs using curses will set @code{CBREAK}
mode.

@emph{Note:} @code{cbreak} overrides @code{raw}.  For a discussion of
how these routines interact with @code{echo} and @code{noecho}
@xref{Input, read-char}.
@end defun

@defun raw
@defunx noraw
The terminal is placed into or out of @code{RAW} mode.  @code{RAW} mode
is similar to @code{CBREAK} mode, in that characters typed are
immediately passed through to the user program.  The differences are
that in @code{RAW} mode, the interrupt, quit, suspend, and flow control
characters are passed through uninterpreted, instead of generating a
signal.  @code{RAW} mode also causes 8-bit input and output.  The
behavior of the @code{BREAK} key depends on other bits in the terminal
driver that are not set by curses.
@end defun

@defun echo
@defunx noecho
These routines control whether characters typed by the user are echoed
by @code{read-char} as they are typed.  Echoing by the tty driver is
always disabled, but initially @code{read-char} is in @code{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 @code{noecho}.
For a discussion of how these routines interact with @code{echo} and
@code{noecho} @xref{Input, read-char}.
@end defun

@defun nl
@defunx nonl
These routines control whether @key{LFD} is translated into @key{RET}
and @code{LFD} on output, and whether @key{RET} is translated into
@key{LFD} on input.  Initially, the translations do occur.  By disabling
these translations using @code{nonl}, curses is able to make better use
of the linefeed capability, resulting in faster cursor motion.
@end defun

@defun resetty
@defunx savetty
These routines save and restore the state of the terminal modes.
@code{savetty} saves the current state of the terminal in a buffer and
@code{resetty} restores the state to what it was at the last call to
@code{savetty}.
@end defun

@node Window Manipulation, Output, Terminal Mode Setting, Curses
@subsection Window Manipulation

@defun newwin nlines ncols begy begx
Create and return a new window with the given number of lines (or rows),
@var{nlines}, and columns, @var{ncols}.  The upper left corner of the
window is at line @var{begy}, column @var{begx}.  If either @var{nlines}
or @var{ncols} is 0, they will be set to the value of
@code{LINES}-@var{begy} and @code{COLS}-@var{begx}.  A new full-screen
window is created by calling @code{newwin(0,0,0,0)}.
@end defun

@defun subwin orig nlines ncols begy begx
Create and return a pointer to a new window with the given number of
lines (or rows), @var{nlines}, and columns, @var{ncols}.  The window is
at position (@var{begy}, @var{begx}) on the screen.  This position is
relative to the screen, and not to the window @var{orig}.  The window is
made in the middle of the window @var{orig}, so that changes made to one
window will affect both windows.  When using this routine, often it will
be necessary to call @code{touchwin} or @code{touchline} on @var{orig}
before calling @code{force-output}.
@end defun

@defun close-port win
Deletes the window @var{win}, freeing up all memory associated with it.
In the case of sub-windows, they should be deleted before the main
window @var{win}.
@end defun

@defun refresh
@defunx force-output win
These routines are called to write output to the terminal, as most other
routines merely manipulate data structures.  @code{force-output} copies
the window @var{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
@code{leaveok} has been enabled, the physical cursor of the terminal is
left at the location of window @var{win}'s cursor.  With @code{refresh},
the number of characters output to the terminal is returned.
@end defun

@defun mvwin win y x
Move the window @var{win} so that the upper left corner will be at position
(@var{y}, @var{x}).  If the move would cause the window @var{win} to be off the
screen, it is an error and the window @var{win} is not moved.
@end defun

@defun overlay srcwin dstwin
@defunx overwrite srcwin dstwin

These routines overlay @var{srcwin} on top of @var{dstwin}; that is, all
text in @var{srcwin} is copied into @var{dstwin}.  @var{srcwin} and
@var{dstwin} need not be the same size; only text where the two windows
overlap is copied.  The difference is that @code{overlay} is
non-destructive (blanks are not copied), while @code{overwrite} is
destructive.
@end defun

@defun touchwin win
@defunx touchline win start count
Throw away all optimization information about which parts of the window
@var{win} have been touched, by pretending that the entire window
@var{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.  @code{touchline} only pretends that
@var{count} lines have been changed, beginning with line @var{start}.
@end defun

@defun wmove win y x
The cursor associated with the window @var{win} is moved to line (row) @var{y},
column @var{x}.  This does not move the physical cursor of the terminal
until @code{refresh} (or @code{force-output}) is called.  The position
specified is relative to the upper left corner of the window @var{win},
which is (0, 0).
@end defun

@node Output, Input, Window Manipulation, Curses
@subsection Output

@noindent
These routines are used to @dfn{draw} text on windows

@defun display ch win
@defunx display str win
@defunx wadd win ch
@defunx wadd win str
The character @var{ch} or characters in @var{str} are put into the
window @var{win} at the current cursor position of the window and the
position of @var{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 @var{ch} is a @key{TAB}, @key{LFD}, or backspace, the cursor will be
moved appropriately within the window @var{win}.  A @key{LFD} also does a
@code{wclrtoeol} before moving.  @key{TAB} characters are considered to
be at every eighth column.  If @var{ch} is another control character, it
will be drawn in the @kbd{C-x} notation.  (Calling @code{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 @code{standout},
below.

@emph{Note:} For @code{wadd} @var{ch} can be an integer and will insert
the character of the corresponding value.
@end defun

@defun werase win
This routine copies blanks to every position in the window @var{win}.
@end defun

@defun wclear win
This routine is like @code{werase}, but it also calls @ref{Output
Options Setting, clearok}, arranging that the screen will be cleared
completely on the next call to @code{refresh} or @code{force-output} for
window @var{win}, and repainted from scratch.
@end defun

@defun wclrtobot win
All lines below the cursor in window @var{win} are erased.  Also, the
current line to the right of the cursor, inclusive, is erased.
@end defun

@defun wclrtoeol win
The current line to the right of the cursor, inclusive, is erased.
@end defun

@defun wdelch win
The character under the cursor in the window @var{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.
@end defun

@defun wdeleteln win
The line under the cursor in the window @var{win} is deleted.  All lines
below the current line are moved up one line.  The bottom line @var{win}
is cleared.  The cursor position does not change.  This does not imply
use of the hardware ``deleteline'' feature.
@end defun

@defun winsch win ch
The character @var{ch} is inserted before the character under the
cursor.  All characters to the right are moved one @key{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.
@end defun

@defun 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.
@end defun

@defun scroll win
The window @var{win} is scrolled up one line.  This involves moving the
lines in @var{win}'s data structure.  As an optimization, if @var{win}
is stdscr and the scrolling region is the entire window, the physical
screen will be scrolled at the same time.
@end defun

@node Input, Curses Miscellany, Output, Curses
@subsection Input

@defun read-char win
A character is read from the terminal associated with the window
@var{win}.  Depending on the setting of @code{cbreak}, this will be
after one character (@code{CBREAK} mode), or after the first newline
(@code{NOCBREAK} mode).  Unless @code{noecho} has been set, the
character will also be echoed into @var{win}.

When using @code{read-char}, do not set both @code{NOCBREAK} mode
(@code{nocbreak}) and @code{ECHO} mode (@code{echo}) at the same time.
Depending on the state of the terminal driver when each character is
typed, the program may produce undesirable results.
@end defun

@defun winch win
The character, of type chtype, at the current position in window
@var{win} is returned.  If any attributes are set for that position,
their values will be OR'ed into the value returned.
@end defun

@defun getyx win
A list of the y and x coordinates of the cursor position of the window
@var{win} is returned
@end defun

@node Curses Miscellany,  , Input, Curses
@subsection Curses Miscellany

@defun wstandout win
@defunx wstandend win

These functions set the current attributes of the window @var{win}.  The
current attributes of @var{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.

@code{wstandout} sets the current attributes of the window @var{win} to
be visibly different from other text.  @code{wstandend} turns off the
attributes.
@end defun

@defun box win vertch horch
A box is drawn around the edge of the window @var{win}.  @var{vertch}
and @var{horch} are the characters the box is to be drawn with.  If
@var{vertch} and @var{horch} are 0, then appropriate default characters,
@code{ACS_VLINE} and @code{ACS_HLINE}, will be used.

@emph{Note:} @var{vertch} and @var{horch} can be an integers and will
insert the character (with attributes) of the corresponding values.
@end defun

@defun unctrl c
This macro expands to a character string which is a printable
representation of the character @var{c}.  Control characters are
displayed in the @kbd{C-x} notation.  Printing characters are displayed
as is.
@end defun

@node Sockets,  , Curses, Packages
@section Sockets

@noindent
These procedures (defined in @file{socket.c}) provide a Scheme interface
to most of the C @dfn{socket} library.  For more information on sockets,
@xref{Sockets, , , libc, The GNU C Library Reference Manual}.

@menu
* Host Data::                   
* Internet Addresses::          
* Socket::                      
@end menu

@node Host Data, Internet Addresses, Sockets, Sockets
@subsection Host Data, Network, Protocol, and Service Inquiries

@defvr Constant af_inet
@defvrx Constant af_unix
Integer family codes for Internet and Unix sockets, respectively.
@end defvr

@defun gethost host-spec
@defunx gethost
Returns a vector of information for the entry for @code{HOST-SPEC} or the
next entry if @code{HOST-SPEC} isn't given.  The information is:

@enumerate 0
@item
host name string
@item
list of host aliases strings
@item
integer address type (@code{AF_INET})
@item
integer size of address entries (in bytes)
@item
list of integer addresses
@end enumerate
@end defun

@defun sethostent stay-open
@defunx sethostent
Rewinds the host entry table back to the begining if given an argument.
If the argument @var{stay-open} is @code{#f} queries will be be done
using @code{UDP} datagrams.  Otherwise, a connected @code{TCP} socket
will be used.  When called without an argument, the host table is
closed.
@end defun

@defun getnet name-or-number
@defunx getnet
Returns a vector of information for the entry for @var{name-or-number} or
the next entry if an argument isn't given.  The information is:

@enumerate 0
@item
official network name string
@item
list of network aliases strings
@item
integer network address type (@code{AF_INET})
@item
integer network number
@end enumerate
@end defun

@defun setnetent stay-open
@defunx setnetent
Rewinds the network entry table back to the begining if given an
argument.  If the argument @var{stay-open} is @code{#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.
@end defun

@defun getproto name-or-number
@defunx getproto
Returns a vector of information for the entry for @var{name-or-number} or
the next entry if an argument isn't given.  The information is:

@enumerate
@item
official protocol name string
@item
list of protocol aliases strings
@item
integer protocol number
@end enumerate
@end defun

@defun setprotoent stay-open
@defunx setprotoent
Rewinds the protocol entry table back to the begining if given an
argument.  If the argument @var{stay-open} is @code{#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.
@end defun

@defun getserv name-or-port-number protocol
@defunx getserv
Returns a vector of information for the entry for @var{name-or-port-number}
and @var{protocol} or the next entry if arguments aren't given.  The
information is:

@enumerate 0
@item
official service name string
@item
list of service aliases strings
@item
integer port number
@item
protocol
@end enumerate
@end defun

@defun setservent stay-open
@defunx setservent
Rewinds the service entry table back to the begining if given an
argument.  If the argument @var{stay-open} is @code{#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.
@end defun

@node Internet Addresses, Socket, Host Data, Sockets
@subsection Internet Addresses

@defun inet:string->address string
Returns the host address number (integer) for host @var{string} or
@code{#f} if not found.
@end defun

@defun inet:address->string address
Converts an internet (integer) address to a string in numbers and dots
notation.  This is an inverse function to inet:address.
@end defun

@defun inet:network address
Returns the network number (integer) specified from @var{address} or
@code{#f} if not found.
@end defun

@defun inet:local-network-address address
Returns the integer for the address of @var{address} within its local
network or @code{#f} if not found.
@end defun

@defun inet:make-address network local-address
Returns the Internet address of @var{local-address} in @var{network}.
@end defun

@node Socket,  , Internet Addresses, Sockets
@subsection 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):
@example
(require 'i/o-extensions)
(define i-port (duplicate-port sock-port "r"))
(define o-port (duplicate-port sock-port "w"))
@end example

@defun make-stream-socket family
@defunx make-stream-socket family protocol

Returns a @code{SOCK_STREAM} socket of type @var{family} using
@var{protocol}.  If @var{family} has the value @code{AF_INET},
@code{SO_REUSEADDR} will be set.  The integer argument @var{protocol}
corresponds to the integer protocol numbers returned (as vector
elements) from @code{(getproto)}.  If the @var{protocol} argument is not
supplied, the default (0) for the specified @var{family} is used.  SCM
sockets look like ports opened for neither reading nor writing.
@end defun

@defun make-stream-socketpair family
@defunx make-stream-socketpair family protocol

Returns a pair (cons) of connected @code{SOCK_STREAM} (socket) ports of
type @var{family} using @var{protocol}.  Many systems support only
socketpairs of the @code{af-unix} @var{family}.  The integer argument
@var{protocol} corresponds to the integer protocol numbers returned (as
vector elements) from (getproto).  If the @var{protocol} argument is
not supplied, the default (0) for the specified @var{family} is used.
@end defun

@defun socket:shutdown socket how
Makes @var{socket} no longer respond to some or all operations depending on
the integer variable @var{how}:

@enumerate 0
@item
Further input is disallowed.
@item
Further output is disallowed.
@item
Further input or output is disallowed.
@end enumerate

@code{Socket:shutdown} returns @var{socket} if successful, @code{#f} if
not.
@end defun

@defun socket:connect inet-socket host-number port-number
@defunx socket:connect unix-socket pathname
Returns @var{socket} (changed to a read/write port) connected to the
Internet socket on host @var{host-number}, port @var{port-number} or
the Unix socket specified by @var{pathname}.  Returns @code{#f} if not
successful.
@end defun

@defun socket:bind inet-socket port-number
@defunx socket:bind unix-socket pathname
Returns @var{inet-socket} bound to the integer @var{port-number} or the
@var{unix-socket} bound to new socket in the file system at location
@var{pathname}.  Returns @code{#f} if not successful. Binding a
@var{unix-socket} creates a socket in the file system that must be
deleted by the caller when it is no longer needed (using
@code{delete-file}).
@end defun

@defun socket:listen socket backlog
The bound (@pxref{Sockets, socket-bind}) @var{socket} is readied to
accept connections.  The positive integer @var{backlog} specifies how
many pending connections will be allowed before further connection
requests are refused.  Returns @var{socket} if successful, @code{#f} if
not.
@end defun

@defun socket:accept socket
Accepts a connection on a bound, listening @var{socket}.  Returns an
input/output port for the connection.

For example:
@example
(let ((sock (socket:bind (make-stream-socket af_inet) 8001)))
  (socket:listen sock 5)
  (do ((connection (socket:accept sock) (socket:accept sock)))
      (#f)
    (handle-client-connection connection))))
@end example

A type @dfn{socket-name} is used for inquiries about open sockets in the
following procedures:
@end defun

@defun getsockname socket
Returns the socket-name of @var{socket}.  Returns @code{#f} if
unsuccessful or @var{socket} is closed.
@end defun

@defun getpeername socket
Returns the socket-name of the socket connected to @var{socket}.
Returns @code{#f} if unsuccessful or @var{socket} is closed.
@end defun

@defun socket-name:family socket-name
Returns the integer code for the family of @var{socket-name}.
@end defun

@defun socket-name:port-number socket-name
Returns the integer port number of @var{socket-name}.
@end defun

@defun socket-name:address socket-name
Returns the integer Internet address for @var{socket-name}.
@end defun

@node Guile Facilities, Internals, Packages, Top
@chapter Guile Facilities

Using SCM as a base, GUILE is a being developed to be a GNU scripting
language.

One design goal of GUILE is to fully support a large body of Emacs lisp
code and a large population of Emacs lisp programmers.  GUILE
accomplishes this goal by means of a translator that rewrites elisp
programs as equivalent programs in extended GUILE Scheme.  We anticipate
a port of the GNU Emacs built-ins to the GUILE environment.

Tom Lord (Lord@@cygnus.com) is coordinating GUILE's development.

@menu
* Locked Vectors::              You can define the layout of new types.
* Exceptions::                  Cheap CATCH/THROW for errors and exits.
* System Exceptions::           All error conditions can be caught by Scheme code.
* Variables::                   First class locatives for top level variables.
* User Defined Top Levels::     You can control the symbol->variable mapping.
* Obarrays::                    First class tables for interning symbols.
* Keywords::                    
* Procedure Properties::        
* Dynamic Roots::               Creating uncapturable continuations.
* Tcl Facilities::              Mutual calling between Tcl and Scheme.
* Tk Facilities::               Accessing Tk from Scheme.
* Gwish::                       A Wish-like application of Guile.
* System Calls::                You can choose to ignore errors safely.
* Gscsh::                       Shell and systems programming features.
@end menu

@node Locked Vectors, Exceptions, Guile Facilities, Guile Facilities
@section Locked Vectors

Locked vectors @dfn{lvectors} are a low level means by which Scheme code
can define the representation of new types.  They are not themselves
especially easy to use, but useful system can be built on top of them
(for example, @pxref{Records, , , slib, SLIB}).

User code should be selective about using lvector functions.  Lvectors
are intended as the representation for user-defined types.  Types which
otherwise have nothing to do with one another may have in common an
lvector representation.  Using lvector functions in a context other than
defining a new type or family of types is likely to be an unsupported
violation of abstractions -- something you generally only want to do
when you are debugging or are willing to write @emph{hacked up} (in the
pejorative sense) code.

Locked vectors have an internal representation similar to vectors.
They are represented by a contiguous array in memory.  Access and
modifications to fields can be done in constant time.  Like vectors,
fields of a locked vector are addressed by integer addresses, based at
0.

The 0 element of a locked vector is special.  It is called the @dfn{key
vector}.  It's use is comparable to that of type objects in other
systems.

The key vector must always be present (there is no such thing as a 0
length lvector).  It must be a (normal) vector with at least as many
elements as the lvector.  The elements of the key vector are used as keys
which control access to the corresponding elements of the lvector.

Keys are used this way: Procedures like lvector-ref and lvector-set!
take a @dfn{key argument} in addition to the lvector and field index.
The key argument is compared to the indexed element of the key vector.
If they are the same (@code{eq?}), access to the lvector is granted.
If an access or modification fails because of an incorrect key, it may
be retried.

If element 0 of the key vector is itself an lvector, the
first several elements of that lvector may be hook functions.  These
hook functions are used to extend the behavior of built-in procedures.
Hook functions are explained in more detail at the end of this
section.

@menu
* Lvector Procedures::          
* Key-Vector 0 Elements::       
@end menu

@node Lvector Procedures, Key-Vector 0 Elements, Locked Vectors, Locked Vectors
@subsection Lvector Procedures

@defun lock-vector! vec

Modify @var{vec} so that it is a locked vector instead of a vector.  Once it
is locked, ordinary vector operations no longer apply to @var{vec}, and
@code{vector?} returns @code{#f} for @var{vec}.

In order to be locked, @var{vec} must have at least one element.  The 0
element of @var{vec} must be a key vector (see above).

@code{lock-vector!} is currently the only way to construct a locked
vector.  However, the decision to create locked vectors by mutating
vectors is a dubious one.  Therefore, you should only use lock-vector!
by wrapping it around a vector constructor, as in:

@example
(lock-vector! (apply vector (cons key-vector field-inits)))
@end example

Following this convention will make it easier to replace lock-vector!
with a more reasonable constructor later.
@end defun

@defun unlock-vector! lvec
Modify @var{lvec} so that it is once again the vector passed to
@code{lock-vector!}.

You should only use @code{unlock-vector!} for debugging.  It is not
guaranteed to be present in future versions of Guile.
@end defun

@defun lvector-ref lvec key index
Return the @var{index}th element of @var{lvec}.

If @var{key} matches the @var{index}th element of the key vector of
@var{lvec}, then the @var{index}th element of @var{lvec} is returned.
If the key does not match, then the @code{ref-fn} hook is tried (hooks
are documented below).  If the @var{index}th element can not be
unlocked, an error is signaled.
@end defun

@defun lvector-set! lvec key index val
Set the @var{index}th element of @var{lvec}.

If @var{key} matches the @var{index}th element of the key vector of
@var{lvec}, then the @var{index}th element of @var{lvec} is set.  If the
key does not match, then the @code{set-fn} hook is tried (see below).
If the @var{index}th element can not be unlocked, an error is signaled.
@end defun

@defun lvector? obj
True if OBJ is indeed a locked vector.
@end defun

@defun lvector-keys lvec
Return the key vector of @var{lvec}, a locked vector.
@end defun

@defun lvector-accessor key-vec index
Return an accessor for @var{key-vec} and @var{index}.  This function is
defined as:

@example
(define (lvector-accessor keyvec index)
   (lambda (lvec)
      (lvector-ref lvec (vector-ref keyvec index) index)))
@end example

However, the built-in version returns an accessor function that is faster
than what the above code would return.
@end defun

@defun lvector-modifier key-vec index
Return an modifier for @var{key-vec} and @var{index}.

This function is defined as:

@example
(define (lvector-modifier keyvec index)
   (lambda (lvec val)
      (lvector-set!  lvec (vector-ref keyvec index) index val)))
@end example

However, the built-in version returns an modifier function that is faster
than what the above code would return.
@end defun

@defun lvector-isa? lvector key-vector
Return @code{#t} if @var{lvector}'s 0th element is @code{eq?} to
@var{key-vector}.

If @var{key-vector} is not equal to element 0, lvector-isa? may yet return a
true value -- it returns the (arbitrary) return value of of the
isa-fn?, if that hook is provided.
@end defun

@node Key-Vector 0 Elements,  , Lvector Procedures, Locked Vectors
@subsection Key-Vector 0 Elements

The first element of the key vector is special.  It may refer to a
number of hook functions used by the lvector procedures and other
parts of the run time system.

The 0 element of a key vector may (optionally) be an lvector called
@dfn{the type lvector}.  A type lvector is characterized by having as a
key the procedure @code{lvector-ref} for elements at offsets where hook
functions are expected.

The hook function offsets are bound to the variables
@var{lvector-hook-<fn>}; so the @var{ref-fn} is at the offset bound to
@var{lvector-ref-fn}, the @var{set-fn} to @var{lvector-set-fn} and so
on.

The order and position of the hooks is explicitly specified:

@enumerate 1
@item ref-fn
@item set-fn
@item print-fn
@item equal-fn
@item isa-fn
@end enumerate

Here is how they are used:

@deffn Hook ref-fn lvec key index
This function is called by @code{lvector-ref} for illegal keys.  A
@var{key} is illegal if it is not @code{eq?} to the @var{index}th key of
the key vector of @var{lvec}.  The @code{ref-fn} hook may return a value
for @code{lvector-ref} or can signal an error.  The default action is to
signal an error.
@end deffn

@deffn Hook set-fn lvec key index val
This function is called by @code{lvector-set!} for illegal keys.  This
hook can interpret the assignment arbitrarily, including signal an
error.  It can return a value for @code{lvector-set!}.  The default
action is to signal an error.
@end deffn

@deffn Hook print-fn lvec port writing?
This function, if present, is called whenever the object is printed.  It
should print the object on @var{port}.  @var{writing?}, if @code{#t},
indicates that the value is being @code{write}n; if @code{#f} --
@code{display}ed.  The print function should return a true value if it
succeeds.  It should return @code{#f} for objects which it can not
print.  In that case, a generic print routine for @dfn{unknown objects}
is used. The default action (if no @var{print-fn} is supplied) is to
print something like: @samp{#<locked-vector 0x7856af8>}.
@end deffn

@deffn Predicate equal-fn? lvec lvec2
If present, called to evaluate @code{(equal? lvec lvec2)}.
The default action is a member-wise comparison of the two lvecs.
Note that the first argument to @code{equal?} chooses the hook function.
@end deffn

@deffn Predicate isa-fn? lvec key-vector
If present, this may be called by @code{lvector-isa?}.

If @var{key-vector} is eq to lvecs key-vector, then @code{lvector-isa?}
simply returns @code{#t}.  If not, if the isa-fn is present, it is
called.  The default action is to return @code{#f}.
@end deffn

Any of the hooks may be @code{#f} specifying that the default action
should be used.

@defvar lvector-hook-slots
The variable @code{lvector-hook-slots} is bound to the number of hook
slots looked for by the run time system.  A type lvector should have at
least that many fields.
@end defvar

Here is an illustration of the construction of lvectors.  Note that two
lvectors are built -- one to hold the hook functions, and then the one
for @dfn{user code}.

@example
;; Create a key vector compatible with the run-time system's
;; way of finding hook functions.
;;
(define a-type-keyvec
  ;; The run-time system uses procedure lvector-ref as the key
  ;; to access hook functions.  You could define type keyvecs
  ;; with more elements if you had a use for them.
  ;;
  (make-vector lvector-hook-slots lvector-ref))

;; Lock up user-provided hook functions for the run-time system.
;; A var-args implementation would make more sense -- it would
;; make it easier to add hooks later.  The example is written
;; this way just to provide a reference for the proper order
;; of hook functions within the lvector.
;;
(define (make-type-lvector ref-hook set-hook print-hook
                           equal-hook isa-hook)
  (lock-vector! (vector a-type-keyvec
                        ref-hook
                        set-hook
                        print-hook
                        equal-hook
                        isa-hook)))

;; Turn a list of field keys into a key vector of a particular
;; type:
;;
(define (make-key-vector type-lvector . field-keys)
  (apply vector (cons type-lvector field-keys)))

;; Turn a key-vector and list of field initializers into
;; a locked vector.  Note that lock-vector! does some error
;; checking on the lengths of the input arguments.
;;
(define (make-object key-vector . field-inits)
  (lock-vector! (apply (vector (cons key-vector field-inits)))))
@end example

@node Exceptions, System Exceptions, Locked Vectors, Guile Facilities
@section Exceptions

These are the low level entry points to exceptions.  Individual subsystems may
define their own uses for exceptions.

@defun catch key thunk handler
Invoke @var{thunk} in the dynamic context of @var{handler} for
excpetions matching @var{key}.  If thunk throws to the symbol @var{key},
then @var{handler} is invoked this way:

@example
(handler key args ...)
@end example

@var{key} may be a symbol.  In that case, @var{thunk} takes no
arguments.  If @var{thunk} returns normally, that is the return value of
@code{catch}.

Handler is invoked outside the scope of its own @code{catch}.  If
@var{handler} against throws to the same key, a new handler from further up
the call chain is invoked.

If the key is #t, then a throw to any symbol will match this call
to @code{catch}.

Key may also be the value @code{#f}.  In that case, @var{thunk} takes
one argument which will be passed a @dfn{jump buffer object}.  A jump
buffer object may be used as the key argument to @code{throw} to throw
to a specific @code{catch} without an intervening search for a symbolic
key.
@end defun

@defun throw key args ...
@defunx throw key
Invoke the catch form matching @var{key}, passing @var{args} to the
@var{handler}.  

If the key is a symbol it will match catches of the same
symbol or of #t.  If no catch matches, the @code{throw-default-handler}
property of the key is checked.  If it is bound to a procedure,
that procedure is called:

@example
(handler key args ...)
@end example

That procedure is called the @dfn{default handler}.

If there is no handler at all, or if the default handler returns to its
caller, an error is signaled.

It is traditional in Scheme to implement exception systems using
@code{call-with-current-continuation}, but his has not been done, for
performance reaons.  The implementation of
@code{call-with-current-continuation} is a stack copying implementation.
This allows it to interact well with ordinary C code.  Unfortunately, a
stack-copying implementation can be slow -- creating a new continuation
involves a block copy of the stack.

Instead of using @code{call-with-current-continuation}, the exception
primitives are implemented as built-ins that take advantage of the
@emph{upward only} nature of exceptions.
@end defun

@node System Exceptions, Variables, Exceptions, Guile Facilities
@section System Exceptions

These two expressions are equivalent:

@example
(error arg ...)
       
(throw 'error arg ...)
@end example

The following are the names of excpetions that may be thrown by the
interpreter itself.

@example
ARGn		"Wrong type argument"
ARG1		"Wrong type argument in position 1"
ARG2		"Wrong type argument in position 2"
ARG3		"Wrong type argument in position 3"
ARG4	        "Wrong type argument in position 4"
ARG5		"Wrong type argument in position 5"
WNA		"Wrong number of arguments"
OVFLOW		"Numerical overflow"
OUTOFRANGE	"Argument out of range"
NALLOC		"Could not allocate"
HUP_SIGNAL	"hang-up"
INT_SIGNAL	"user interrupt"
FPE_SIGNAL	"arithmetic error"
BUS_SIGNAL	"bus error"
SEGV_SIGNAL	"segmentation violation"
ALRM_SIGNAL	"alarm"

read-sharp-error
@end example



@node Variables, User Defined Top Levels, System Exceptions, Guile Facilities
@section Variables

All top level bindings are stored in locations called @dfn{variables}.
Variables are first class objects.

@defun make-variable init
@defunx make-variable init name-hint
Return a new variable, bound to @var{init}.

The optional @var{name-hint} is a symbolic name for the variable.  It
will be used in some error messages relating to the variable.
@end defun

@defun variable-ref variable
Return the current binding of @var{variable}.

It is an error to call @code{variable-ref} on a variable which is
unbound.
@end defun

@defun variable-set! variable value
Modify the binding of @var{variable}.
@end defun

@defun builtin-variable name
Return the built-in variable for named @var{name}.  @var{name} must be a
symbol.

Even symbols with no top level bindings have built-in variables.
There is an unbounded supply of undefined variables.
@end defun

@deffn Predicate variable? obj
Return @code{#t} if @var{obj} is a variable;  @code{#f} otherwise.
@end deffn

@deffn Predicate variable-bound? var
Return @code{#t} if @var{var} is a bound variable; @code{#f} otherwise.
@end deffn

@defun make-undefined
@defunx make-undefined name-hint
Return a new variable, initially unbound.

The optional @var{name-hint} a symbolic name for the variable.  It will
be used in some error messages relating to the variable.
@end defun


@node User Defined Top Levels, Obarrays, Variables, Guile Facilities
@section User Defined Top Levels

Low level support is provided for multiple top levels.  This procedure
should only be used advisadly.  Most people should stick to the
@dfn{user level module system interface}.

@defun eval2 form env-fn
Evaluate @var{form} in the top level environment described by
@var{env-fn}.

@var{env-fn} is called this way:
@example
(env-fn name defining)
@end example

Return a variable object for the symbol @var{name}.  Returning @code{#f}
indicates that @var{name} has no binding.

The boolean @var{defining} is @code{#t}, then the lookup is for a
@code{define} form or the equivalent -- a new variable may be created if
none already exists.

If @code{#f}, then the request should not create a new binding.
@end defun


@node Obarrays, Keywords, User Defined Top Levels, Guile Facilities
@section Obarrays

An @dfn{obarray} is an ordinary Scheme vector, used in a particular way.
It represents two mapping: a mapping of strings to symbols, and a
mapping of symbols to arbitrary values.

To initialize an obarray, create a vector of any non-0 size, filled with
the empty list.  Thereafter, referring to the contents of the vector
yields unspecified values.  (You might be able guess the detailed
representation of obarrays by examining the array, but if your code
depends on that representation, it might easily break in future versions
of Guile.)

@defun intern-string obarray name
Return the @var{symbol} bound to the string@var{name} in @var{obarray}.

If there is no such symbol, a new @var{symbol} is allocated.
@var{obarray} may be @code{#f} which guarantees that a new @var{symbol}
is returned.
@end defun

@defun intern-symbol obarray symbol
Add @var{symbol} to @var{obarray}.  If @var{symbol} is already present,
this has no effect.

After this addition, @var{symbol} is the symbol binding of its name.
That is, even if another symbol of the same name was previously interned
in @var{obarray}, @var{symbol} becomes the binding of that name after
intern-symbol.  (This does not mean that the previous symbol is removed
from the @var{obarray}).
@end defun


@defun symbol-interned? obarray symbol
Return @code{#t} if @var{symbol} is in @var{obarray}.
@end defun

@defun symbol-bound? obarray symbol
@defunx symbol-binding obarray symbol
@defunx symbol-set! obarray symbol value
A @var{symbol} in an @var{obarray} may be bound arbitrarily.  The
binding may be changed.  When first interned, a symbol is unbound.
@end defun

@node Keywords, Procedure Properties, Obarrays, Guile Facilities
@section Keywords

A @dfn{keyword} is a self-evaluating symbol-like object with a 
convenient read syntax.

@example
        (keyword? :keyword) => #t
@end example

@defun make-keyword symbol
Construct a keyword form a symbol.

The first character of the symbol's name must be '-'.  

@example
        (make-keyword '-command) => :command
@end example
@end defun 

@defun keyword? obj
Return @code{#f} unless @var{obj} is a keyword object.
@end defun 

@defun keyword->symbol keyword
Return the symbol that corresponds to a keyword.

@example
        (keyword->symbol :text) => -text
@end example
@end defun 

@node Procedure Properties, Dynamic Roots, Keywords, Guile Facilities
@section Procedure Properties

Procedures created using "define" or "lambda" have a binding slot which
you can use arbitrarily.  Many parts of the system will presume that
this slot will contain a (possible empty) assoc list, keyed by symbols
(`procedure properties').  If your procedure will be manipulated by a
part of the system which is documented as using property lists, you
should follow the convention, and use a unique prefix for all property
names that you define.  Procedures which do not escape to such parts of
the system can hve any value at all in their binding slot.

It is an arbitrary restriction that (some) built-in procedures lack a
binding slot.  This ought to be fixed.  The reason it hasn't been fixed
already is that the representation of the binding slot has to be chosen
carefully for built-in procedure types.

@defun procedure-properties procedure
@defunx set-procedure-properties! procedure value
Return or set the value held in a procedures binding slow.
@end defun

@defun procedure-property proc key
@defunx procedure-assoc proc key
@defunx procedure-putprop! proc key value
Retrieve or get the binding of a particular procedure property.

These functions assume that the binding slot of the procedure holds an
assoc list.

@code{procedure-property} returns the binding of the property while
@code{procedure-assoc} returns the key-value pair that holds the binding.
@end defun


@node Dynamic Roots, Tcl Facilities, Procedure Properties, Guile Facilities
@section Dynamic Roots

A @dfn{dynamic root} is a root frame of Scheme evaluation.
The top-level repl, for example, is an instance of a dynamic root.

Each dynamic root has its own chain of dynamic-wind information.  Each
has its own set of continuations, jump-buffers, and pending CATCH
statements which are inaccessible from the dynamic scope of any
other dynamic root.

In a thread-based system, each thread has its own dynamic root.  Therefore,
continuations created by one thread may not be invoked by another. [Thread
support is not yet fully implemented.]

Even in a single-threaded system, it is sometimes useful to create a new
dynamic root.  For example, if you want to apply a procedure, but to
not allow that procedure to capture the current continuation, calling
the procedure under a new dynamic root will do the job.

@defun call-with-dynamic-root thunk error-thunk
Evaluate @var{(thunk)} in a new dynamic context, returning its value.

If an error occurs during evaluation, call error-thunk, passing it an
error code describing the condition.  [Error codes are currently
meaningless integers.  In the future, real values will be specified.]
If this happens, the error-thunk is called outside the scope of the
new root -- it is called in the same dynamic context in which
call-with-dynamic-root was evaluated.

If THUNK captures a continuation, the continuation is rooted at the call
to THUNK.  In particular, the call to call-with-dynamic-root is not
captured.  Therefore, call-with-dynamic-root always returns at most one
time.

Before calling THUNK, the dynamic-wind chain is un-wound back to the
root and a new chain started for THUNK.  Therefore, this call
may not do what you expect:

@example
;; Almost certainly a bug:
(call-with-output-to-port
 some-port

 (lambda ()
   (call-with-dynamic-root
    (lambda ()
      (display 'fnord)
      (newline))
    (lambda (errcode) errcode))))
@end example

The problem is, on what port will @samp{fnord\n} be displayed?  You
might expect that because of the @code{call-with-input-from-port} that
it will be displayed on the port bound to @code{some-port}.  But it
probably won't -- before evaluating the thunk, dynamic winds are
unwound, including those created by @code{call-with-input-from-port}.
So, the standard output port will have been re-set to its default value
before @code{display} is evaluated.

(This function was added to Guile mostly to help calls to functions in C
libraries that can not tolerate non-local exits or calls that return
multiple times.  If such functions call back to the interpreter, it should
be under a new dynamic root.)
@end defun


@defun dynamic-root
Return an object representing the current dynamic root.

These objects are only useful for comparison using @code{eq?}.
They are currently represented as numbers, but your code should
in no way depend on this.
@end defun


@node Tcl Facilities, Tk Facilities, Dynamic Roots, Guile Facilities
@section Tcl Facilities

If you have Tcl extension modules written in C, these can be accessed
from Guile programs.  If you have an application that uses the Tcl
interpreter, you can use Guile to define new modules for it -- modules
that can be loaded without having to re-compile.

Documented here are the low-level facilities linking Tcl to Guile.  In
the future, a friendlier Scheme interface will be provided in preference
to these entry points.

@defun tcl-create-interp
Return a new Tcl interpreter object.

An interpreter object is a namespace of functions and variables managed
by modules that use the Tcl calling conventions.
@end defun 

@defun tcl-global-eval interpreter string
Evaluate a string according to Tcl's evaluation rules.

@var{interpreter} must be an object returned by @code{tcl-create-interp}.

The return value is an integer/string pair.  The integer is the Tcl
status code, the string is the Tcl result.

This is not the way to call a Tcl command.  See the functions @code{tcl-command}
and @code{tcl-apply-command}.  Using those functions is faster.

N.B.: by default, most built-in Tcl commands are absent in Guile.
Consequently, most Tcl programs will not run.  However, facilities
exist so that you can link all of libtcl with Guile programs -- in which
case all the usual built-in commands will be present.  [add reference!]
@end defun

@defun tcl-get-int interpreter string
@defunx tcl-get-double interpreter string
@defunx tcl-get-boolean interpreter string
Convert strings to Scheme types according to the conventions of Tcl.
@end defun

@defun tcl-split-list interpreter string
Split a Tcl-style "list" (a string following Tcl's list syntax) into a list.
@end defun

@defun tcl-merge interpreter list
Combine a list of strings into a string following Tcl's list syntax.
@end defun

@defun tcl-create-command interpreter name procedure
Define a new Tcl command which is recognized by the Tcl evaluator.

@var{interpreter} must be an object returned by @code{tcl-create-command}.

@var{name} must be a string which is a valid Tcl identifier.

@var{procedure} may be any Scheme procedure object.

When the Tcl evaluator invokes the new command, @var{procedure} is
called with as many arguments as were passed to the Tcl command.
The arguments are all passed as strings.

The return value of @var{procedure} is used as the Tcl result.  The
return value of @var{procedure} determines the Tcl return value
according to these rules:

@example
if PROCEDURE returns:      the Tcl result is:   and Tcl status is:
__________________________________________________________________

string (e.g. "foo")           that string ("foo")       TCL_OK

integer (e.g. 1)              the empty string          the int
                                                            (1)

an int/string pair            the string                the int 
(e.g. (1 . "bogus frob"))        ("bogus frob")             (1)
@end example
@end defun

@defun tcl-delete-command interpreter name
Remove the named command from a Tcl interpreter.
@end defun

@defun tcl-trace-var2 interpreter name index flags procedure
@defunx tcl-untrace-var2 interpreter name index flags procedure
Add a callback to a Tcl variable.

@var{name} is the name of the variable.

@var{index} is the subscript of the variable, or @code{#f} for a scalar.

After @code{tcl-trace-var2}, modifications to the named variable or 
array position cause procedure to be called with four arguments:
a tcl interpreter, the variable being modified, an index into the 
named variable (possible the empty string), and an integer of flags.
@end defun


@defun tcl-set-var2 interpreter name index value flags
@defunx tcl-get-var2 interpreter name index flags
Set or return the current value of a Tcl variable.
@end defun

Symbolic names for Tcl flags are provided in the source file Gtcl.scm
and are the same as their C counterparts.  The procedure @code{flags}
is used to combine flags.  For example:

        (flags TCL_TRACE_READS TCL_TRACE_WRITES TCL_TRACE_UNSETS)


Tcl commands can be invoked from Scheme directly, without having to 
use the Tcl evaluator:

@defun tcl-command interpreter name
Return an object representing the named command (or #f if none is defined).
@end defun

@defun tcl-apply-command command args
Apply Tcl command @var{command} to the list of strings @var{args}.

@var{command} should be an object returned by @code{tcl-command}.

@var{args} should be a list of arguments.

The return value is an integer/string pair.  The integer is a Tcl return
code, the string the Tcl result.

The arguments can be of several types but must ultimately be converted
to strings because of the way Tcl and Tk work internally.  Types are
converted this way:

@example
  ;;----------------------------------------
  ;; Argument             Converted argument
  ;;----------------------------------------
    123                     "123"
    123.34                  "123.34"
    "a-string"              "a-string"
    'a-symbol               "a-symbol"
    :keyword                "-keyword"
    #t                      "1"
    #f                      "0"
    (lambda (...) ...)      "*__guile#234"
@end example

The automatic conversion of a procedure works this way.  First, a new
Tcl name is generated for the procedure and a Tcl command with that name
is defined.  When evaluated, the Tcl command calls the Scheme procedure.
Second, if the procedure has a property defined called
'tcl-calling-convention, and if that is bound to a string, then that
string is appended to the name with an intervening space.  For example,
if a procedure's properties bind 'tcl-calling-convention to "%x %y",
then the name is appended and winds up like "__guile#234 %x %y".
Finally, an asterix is prepended to the name (e.g. "*__guile#234 %x %y").

In the GNU modified version of Tcl/Tk, an asterix prepended to a command
name has special meaning if the name is passed as a "-command" or
similar configuration parameter to a widget, or if passed as the command
argument to a "bind" operation.  In that case, the command is renamed to
a canonical name that is unique to the widget or binding sequence
(overwriting any previous definition).  If the widget or binding
sequence is later deleted, so is the canonicalized command.  This is an
extremely twisted way to trick Tcl into managing anonymous Scheme
procedures with acceptable semantics (e.g., without core leaks and
without requiring Scheme programmers to invent liveness for anonymous
procedures they'd otherwise drop).
@end defun

@node Tk Facilities, Gwish, Tcl Facilities, Guile Facilities
@section Tk Facilities

So that Tk widgets can be used form Scheme, Guile provides the following
functions:

@defun tk-init-main-window interpreter display name class
Initialize a Tcl interpreter as a Tk main window.

@var{display}, @var{name}, and @var{class} must all be strings.
@end defun

@defun tk-do-one-event flags
Process one window system event.

Symbolic definitions for @var{flags} are provided in Gtk.scm and have
the same name as their C counterparts.
@end defun

@defun tk-main-loop
Process window events until no windows remain.
@end defun 

@node Gwish, System Calls, Tk Facilities, Guile Facilities
@section Gwish

Gwish is a Wish-like application of Guile, based on STk by Erick
Gallesio.

@subsection Running Gwish

@subsection Mapping Tcl/Tk Constructs onto Gwish

In Gwish, there is a single Tcl/Tk interpreter which is an implicit
default.  Commands defined in that interpreter are automaticly defined
as Scheme commands as well (unless a Scheme-specific binding overwrites
them).  This means that you can write Scheme code that closely matches
the corresponding Tcl code.  For example:

@example
(button '.b)
(.b 'configure :text "hello world" :command (tcl-lambda () (beep)))
@end example

Arguments passed to a procedure implemented by a Tcl command must be
converted to a string for the sake of Tcl's calling conventions and data
representations.  This table illustrates how argument types are converted:

@example
  ;;----------------------------------------
  ;; Argument             Converted argument
  ;;----------------------------------------
    123                     "123"
    123.34                  "123.34"
    "a-string"              "a-string"
    'a-symbol               "a-symbol"
    :keyword                "-keyword"
    #t                      "1"
    #f                      "0"
    (lambda (...) ...)      "*__guile#234"
@end example

Most of these conversions are simple and obvious but the conversion of
procedure objects is subtle and non-obvious.  It is not necessary to
understand the details, though they are documented elsewhere.  It is
necessary to know that procedure arguments `do the right thing' when
they are passed as command parameters to widget configuration commands,
and as event bindings.  You might ask: what is the right thing?

A procedure passed as either an event binding or widget command is protected
by the binding or widget involved.  Effectively, the widget or binding
keeps a reference to the procedure object.  For this reason, it is possible
to use an anonymous Scheme procedure as an event binding or widget command.
For example:

@example
(let ((n 0))
   (.b configure :command (lambda ()
                             (write n)
                             (newline)
                             (set! n + 1)
                             "")))

;; Incidently, note that the command procedure returns an empty string.
;; All procedures called by Tcl have to return a proper Tcl result.
;; Return values are explained further in the next subsection.
;;
@end example

When a command or binding is overwritten and that command or binding is
to a Scheme procedure, the reference to the procedure is dropped.  The
procedure is also dropped if the binding or widget is deleted.  For this
reason, there are no core leaks associated with passing anonymous
procedures as these kinds of arguments.

At this time, it isn't generally useful to pass Scheme procedures to Tcl
commands other than as an argument to a binding command or widget
configuration command.

The details of how procedures are translated are described in the
documentation for `tcl-apply-command'.  @xref{Tcl Facilities}.



@subsection Defining Tcl Command in Scheme

Gwish provides a convenient syntax for defining new Tcl commands.

@deffn Syntax proc name formals . body
Define a new Tcl command and Scheme procedure simultaneously.

@example
;; A two argument string-append callable as a Tcl command.
;;
(proc string-smash (s1 s2)  (string-append s1 s2))
@end example

Proc expands to a @code{tcl-lambda} form, which is explained below.
The example above is equivalent to:

@example
(begin
  (define string-smash (tcl-lambda (s1 s2) (string-append s1 s2)))
  (tcl-create-command the-interpreter 'string-smash string-smash))
@end example

@end deffn

@deffn Syntax tcl-lambda (?calling-convention? ?.? formals) . body
Similar to lambda, but imposes Tcl-specific calling conventions.
Type declarations are supported.  This is best explained via examples.

A simple use of @code{tcl-lambda}:

@example
;; By default, when called from Tcl, all of the arguments 
;; to a tcl-lambda are strings.
;;
(tcl-lambda (a b) (string-append a b))
@end example

The return value of a tcl-lambda has special signficance when the
function is invoked by Tcl.  

An integer return value is converted to a string.  A string or symbol is
used used directly as a Tcl result.  A cons pair with an integer car and
string cdr is a Tcl status/message combination.

Type declarations can be used to specify that parameters passed as
strings should be coerced to some other type.  For example:

@example
(define tcl-plus 
   (tcl-lambda ((number a) (number b))
      (+ a b)))

(tcl-plus "23" 19)  => 42
@end example


Tcl-lambda is very useful for using anonymous Scheme functions
as Tk event bindings.  For this purpose, you can can specify a
Tk "calling convention" by writing a string in the first of
the argument specification.  For example:

@example
(.c 'bind 'node "<Button-2>"
    (tcl-lambda ("%x %y" (number x) (number y))
      (set! cur-x x)
      (set! cur-y y)
      #t))                    ; Tcl-compatible return value.
@end example

In that example, @code{"%x %y"} is the calling convention.  The full command
that Tcl calls when invoking the binding will be similar to:

@example
__binding#0x123123 %x %y
@end example

and therefore the Scheme procedure will be passed (in this case) the x and
y position of the mouse.
@end deffn 

@subsection An Example: Ousterhout's Graph Editor

This program implements the toy graph editor from the Tcl/Tk <fixme>.

@example
@c include Ggraph.scm
@end example



@node System Calls, Gscsh, Gwish, Guile Facilities
@comment  node-name,  next,  previous,  up
@section System Calls

A volunteer is need to write this section.  Most of the system call
documentation already exists in other sections. See also
@xref{I/O-Extensions}, @xref{Posix Extensions}.

All of the unix system calls are available as Scheme procedures.

Any call that fails with errno EINTR is automaticly retried.

By default, any other error during a system call will cause the call
to signal an error and not return.  There are two functions that control
this behavior and which you can redefine.  These are @code{syscall}
and @code{syserror}.  The default definitions are:

@example
(define (syserror key fn err . args)
  (errno err)
  (apply error (cons fn args)))

(define (syscall thunk)
  (errno 0)
  (catch 'syserror thunk syserror))
@end example

A typical system call is written this way:

@example
(define (connect port address . args)
  (syscall
   (lambda ()
     (let ((rv (apply %connect (cons port (cons address args)))))
       (if (eq? rv #f)
	   (throw 'syserror 'connect (errno) port address args))))))
@end example

@node Gscsh,  , System Calls, Guile Facilities
@comment  node-name,  next,  previous,  up
@section Gscsh

@deffn Function fork
@deffnx Function fork thunk
Fork a child process: returns child pid to parent, #f to child.

With an argument, fork a child process executing the Scheme procedure
thunk.  Returns child pid to parent.
@end deffn

@deffn Function wait
@deffnx Function wait pid
@deffnx Function wait pid options
Wait for any child to terminate.

Pid argument means for that child process to terminate.  Special values
for pid are: -1 wait for any child process; 0 wait for any child process
in the process group of the calling process.

Options is an integer with the following OR'd values:
@example
WNOHANG: do not wait.
WUNTRACED: also return status information from stopped processes.
@end example
@end deffn

@deffn Function exec-pipe pipe
@deffnx Function fg-pipe pipe
@deffnx Function bg-pipe pipe
These functions run external programs in a pipeline.  exec-pipe
causes the pipeline to overlay the current process.  fg-pipe
waits for the first command in the pipeline to exit and
returns its exit status code.  bg-pipe runs the pipeline in the
background, returning a list with the process id of the first
program and ports which can be used for communicating with the
programs in the pipeline.

The pipe argument consists of a series of commands and optionally
connection lists.  A command can be either an external Unix
program or a scheme procedure.  An external program is written
as a list of strings with the name and arguments.  An example
of a pipeline connecting three programs and using the default
connection lists is:

@example
(exec-pipe
  '("cat" "/etc/passwd") '("sort" "-t:" "+2") '("grep" "^u"))
@end example

Alternatively a Scheme procedure (taking no arguments) may be
specified and will be run in its own subprocess.  The 
standard ports (current-input-port, current-output-port and
current-error-port) are created automatically from file	
descriptors 0, 1 and 2.  A Scheme procedure used in a
pipeline would typically be a filter, such as:

@example
(define filter
  (lambda ()
    (let loop ((ch (read-char)))
      (cond ((not (eof-object? ch))
	     (display ch)
	     (loop (read-char)))))))
@end example

and the term in the pipeline would be written:
	
@example
`(,filter)	
@end example

A connection list specifies how open Scheme ports are connected
to Unix file descriptors in the programs in the pipeline and
how file descriptors are wired together between programs.
For example, the default connection list between the sort
and grep commands in the pipeline above is:

@example
`((1 0) (2 ,(current-error-port)))
@end example

which says to connect file descriptor 1 (standard output) from
the sort command to file descriptor 0 (standard input) in the
grep command and to connect file descriptor 2 (standard error)
from the sort command to the Scheme current error port.
	
Connection lists may be placed between programs in the pipeline
and if omitted the default above will be used.  Connection
lists may also be placed before the first program and
after the last to specify connections at the beginning and
end of the pipeline.  The default connection list then
depends on which pipeline function is used.

The defaults for exec-pipe and fg-pipe are:

@example
`((,(current-input-port) 0))
`((1 ,(current-output-port)) (2 ,(current-error-port)))
@end example

for the input and output ends of the pipeline respectively.

The defaults for bg-pipe are:

@example
'((return-port 0))
`((1 return-port) (2 ,(current-error-port)))
@end example

The symbol 'return-port in the connection list adds
a port to the list returned by bg-pipe.  In the default
case two ports are returned: the first is an output port
connected to the standard input of the first program in
the pipeline and the second is an input port
connected to the standard output of the last process.
[need to beware of deadlocks if multiple output ports
are returned].
	
The pipeline example above can be rewritten with all the
connection lists given explicitly:

@example
(exec-pipe `((,(current-input-port) 0))
  '("cat" "/etc/passwd") `((1 0) (2 ,(current-error-port)))
  '("sort" "-t:" "+2")   `((1 0) (2 ,(current-error-port)))
  '("grep" "^u") `((1 ,(current-output-port)) (2 ,(current-error-port)))
@end example

Multiple file descriptors can be connected to a single target if a
connection list such as '((1 0) (2 0)) or equivalently '((1 2 0)) is
specified.

A final construction which can be used in a connection list
is a string to be interpreted as the name of a file.
For example, the connection list between the sort and grep
commands could be written:

@example
'((1 0) (2 "sort-errors"))
@end example

which would capture the standard error from sort
to a newly created file.
[Maybe this should be extended to
allow appending to a file, e.g., with ">sort-error-log",
although it could also be done with ports].
@end deffn

@node Internals, Procedure and Macro Index, Guile Facilities, Top
@chapter Internals

@menu
* Data Types::                  
* Operations::                  
* Improvements To Make::        
* Finishing Dynamic Linking::   
@end menu

@node Data Types, Operations, Internals, Internals
@section Data Types

@noindent
In the descriptions below it is assumed that @code{long int}s are 32
bits in length.  Acutally, SCM is written to work with any @code{long
int} size larger than 31 bits.  With some modification, SCM could work
with word sizes as small as 24 bits.

@noindent
All SCM objects are represented by type @dfn{SCM}.  Type @code{SCM} come
in 2 basic flavors, Immediates and Cells:

@menu
* Immediates::                  
* Cells::                       
* Data Type Representations::   
@end menu

@node Immediates, Cells, Data Types, Data Types
@subsection Immediates

@noindent
An @dfn{immediate} is a data type contained in type @code{SCM}
(@code{long int}).  The type codes distinguishing immediate types from
each other vary in length, but reside in the low order bits.

@defmac IMP x
@defmacx NIMP x
Return non-zero if the @code{SCM} object @var{x} is an immediate or
non-immediate type, respectively.
@end defmac

@deftp Immediate inum
immediate 30 bit signed integer.  An INUM is flagged by a @code{1} in
the second to low order bit position.  The high order 30 bits are used
for the integer's value.

@defmac INUMP x
@defmacx NINUMP x
Return non-zero if the @code{SCM} @var{x} is an immediate integer or not
an immediate integer, respectively.
@end defmac

@defmac INUM x
Returns the C @code{long integer} corresponding to @code{SCM} @var{x}.
@end defmac

@defmac MAKINUM x
Returns the @code{SCM} inum corresponding to C @code{long integer} x.
@end defmac

@defvr {Immediate Constant} INUM0
is equivalent to @code{MAKINUM(0)}.
@end defvr

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 @file{scmfig.h} and a signed right shift,
@code{SRS}, is constructed in terms of unsigned right shift.
@end deftp

@deftp Immediate ichr
characters.

@defmac ICHRP x
Return non-zero if the @code{SCM} object @var{x} is a character.
@end defmac

@defmac ICHR x
Returns corresponding @code{unsigned char}.
@end defmac

@defmac MAKICHR x
Given @code{char} @var{x}, returns @code{SCM} character.
@end defmac

@end deftp

@deftp Immediate iflags
These are frequently used immediate constants.
@deftypevr {Immediate Constant} SCM BOOL_T
@code{#t}
@end deftypevr
@deftypevr {Immediate Constant} SCM BOOL_F
@code{#f}
@end deftypevr
@deftypevr {Immediate Constant} SCM EOL
@code{()}.  If @code{SICP} is @code{#define}d, @code{EOL} is
@code{#define}d to be identical with @code{BOOL_F}.  In this case, both
print as @code{#f}.
@end deftypevr
@deftypevr {Immediate Constant} SCM EOF_VAL
end of file token, @code{#<eof>}.
@end deftypevr
@deftypevr {Immediate Constant} SCM UNDEFINED
@code{#<undefined>} used for variables which have not been defined and
absent optional arguments.
@end deftypevr
@deftypevr {Immediate Constant} SCM UNSPECIFIED
@code{#<unspecified>} is returned for those procedures whose return
values are not specified.
@end deftypevr

@end deftp

@defmac IFLAGP n
Returns non-zero if @var{n} is an ispcsym, isym or iflag.
@end defmac

@defmac ISYMP n
Returns non-zero if @var{n} is an ispcsym or isym.
@end defmac

@defmac ISYMNUM n
Given ispcsym, isym, or iflag @var{n}, returns its index in the C array
@code{isymnames[]}.
@end defmac

@defmac ISYMCHARS n
Given ispcsym, isym, or iflag @var{n}, returns its @code{char *}
representation (from @code{isymnames[]}).
@end defmac

@defmac MAKSPCSYM n
Returns @code{SCM} ispcsym @var{n}.
@end defmac

@defmac MAKISYM n
Returns @code{SCM} iisym @var{n}.
@end defmac

@defmac MAKIFLAG n
Returns @code{SCM} iflag @var{n}.
@end defmac

@defvar isymnames
An array of strings containing the external representations of all the
ispcsym, isym, and iflag immediates.  Defined in @file{repl.c}.
@end defvar

@defvr Constant NUM_ISPCSYM
@defvrx Constant NUM_ISYMS
The number of ispcsyms and ispcsyms+isyms, respectively.  Defined in
@file{scm.h}.
@end defvr

@deftp Immediate isym
@code{and}, @code{begin}, @code{case}, @code{cond}, @code{define},
@code{do}, @code{if}, @code{lambda}, @code{let}, @code{let*},
@code{letrec}, @code{or}, @code{quote}, @code{set!}, @code{#f},
@code{#t}, @code{#<undefined>}, @code{#<eof>}, @code{()}, and
@code{#<unspecified>}.

@deftpx {CAR Immediate} ispcsym
special symbols: syntax-checked versions of first 14 isyms
@end deftp

@deftp {CAR Immediate} iloc
indexes to a variable's location in environment
@end deftp

@deftp {CAR Immediate} gloc
pointer to a symbol's value cell
@end deftp

@deftp 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 @code{0}.

There is one exception to this rule, @emph{CAR Immediate}s, described
next.
@end deftp

@noindent
A @dfn{CAR Immediate} is an Immediate point which can only occur in the
@code{CAR}s of evaluated code (as a result of @code{ceval}'s memoization
process).

@node Cells, Data Type Representations, Immediates, Data Types
@subsection Cells

@noindent
@dfn{Cell}s represent all SCM objects other than immediates.  A cell has
a @code{CAR} and a @code{CDR}.  Low-order bits in @code{CAR} identify
the type of object.  The rest of @code{CAR} and @code{CDR} hold object
data.  The number after @code{tc} specifies how many bits are in the
type code.  For instance, @code{tc7} indicates that the type code is 7
bits.

@defmac NEWCELL x
Allocates a new cell and stores a pointer to it in @code{SCM} local
variable @var{x}.

Care needs to be taken that stores into the new cell pointed to by
@var{x} do not create an inconsistent object.  @xref{Signals}.
@end defmac

@noindent
All of the C macros decribed in this section assume that their argument
is of type @code{SCM} and points to a cell (@code{CELLPTR}).

@defmac CAR x
@defmacx CDR x
Returns the @code{car} and @code{cdr} of cell @var{x}, respectively.
@end defmac

@defmac TYP3 x
@defmacx TYP7 x
@defmacx TYP16 x
Returns the 3, 7, and 16 bit type code of a cell.
@end defmac

@deftp Cell tc3_cons
scheme cons-cell returned by (cons arg1 arg2).

@defmac CONSP x
@defmacx NCONSP x
Returns non-zero if @var{x} is a @code{tc3_cons} or isn't, respectively.
@end defmac
@end deftp

@deftp Cell tc3_closure
applicable object returned by (lambda (args) @dots{}).
@code{tc3_closure}s have a pointer to other the body of the procedure in
the @code{CAR} and a pointer to the environment in the @code{CDR}.

@defmac CLOSUREP x
Returns non-zero if @var{x} is a @code{tc3_closure}.
@end defmac

@defmac CODE x
@defmacx ENV x
Returns the code body or environment of closure @var{x}, respectively.
@end defmac

@end deftp

@noindent
@dfn{Header}s are Cells whose @code{CDR}s point elsewhere in memory,
such as to memory allocated by @code{malloc}.

@deftp Header spare
spare @code{tc7} type code
@end deftp

@deftp Header tc7_vector
scheme vector.

@defmac VECTORP x
@defmacx NVECTORP x
Returns non-zero if @var{x} is a @code{tc7_vector} or if not, respectively.
@end defmac

@defmac VELTS x
@defmacx LENGTH x
Returns the C array of @code{SCM}s holding the elements of vector
@var{x} or its length, respectively.
@end defmac
@end deftp

@deftp Header tc7_ssymbol
static scheme symbol (part of initial system)

@deftpx Header tc7_msymbol
@code{malloc}ed scheme symbol (can be GCed)

@defmac SYMBOLP x
Returns non-zero if @var{x} is a @code{tc7_ssymbol} or
@code{tc7_msymbol}.
@end defmac

@defmac CHARS x
@defmacx UCHARS x
@defmacx LENGTH x
Returns the C array of @code{char}s or as @code{unsigned char}s holding
the elements of symbol @var{x} or its length, respectively.
@end defmac
@end deftp

@deftp Header tc7_string
scheme string

@defmac STRINGP x
@defmacx NSTRINGP x
Returns non-zero if @var{x} is a @code{tc7_string} or isn't,
respectively.
@end defmac

@defmac CHARS x
@defmacx UCHARS x
@defmacx LENGTH x
Returns the C array of @code{char}s or as @code{unsigned char}s holding
the elements of string @var{x} or its length, respectively.
@end defmac
@end deftp

@deftp Header tc7_bvect
uniform vector of booleans (bit-vector)
@end deftp

@deftp Header tc7_ivect
uniform vector of integers
@end deftp

@deftp Header tc7_uvect
uniform vector of non-negative integers
@end deftp

@deftp Header tc7_fvect
uniform vector of short inexact real numbers
@end deftp

@deftp Header tc7_dvect
uniform vector of double precision inexact real numbers
@end deftp

@deftp Header tc7_cvect
uniform vector of double precision inexact complex numbers
@end deftp

@deftp Header tc7_contin
applicable object produced by call-with-current-continuation
@end deftp

@deftp Header tc7_cclo
Subr and environment for compiled closure

A cclo is similar to a vector (and is GCed like one), but can be applied
as a function:

@enumerate
@item
the cclo itself is consed onto the head of the argument list
@item
the first element of the cclo is applied to that list.  Cclo invocation
is currently not tail recursive when given 2 or more arguments.
@end enumerate

@defun makcclo proc len
makes a closure from the @emph{subr} @var{proc} with @var{len}-1 extra
locations for @code{SCM} data.  Elements of a @var{cclo} are referenced
using @code{VELTS(cclo)[n]} just as for vectors.
@end defun
@end deftp

@noindent
A @dfn{Subr} is a header whose @code{CDR} points to a C code procedure.
Scheme primitive procedures are subrs.  Except for the arithmetic
@code{tc7_cxr}s, the C code procedures will be passed arguments (and
return results) of type @code{SCM}.

@deftp Subr tc7_asubr
associative C function of 2 arguments.  Examples are @code{+}, @code{-},
@code{*}, @code{/}, @code{max}, and @code{min}.
@end deftp

@deftp Subr tc7_subr_0
C function of no arguments.
@end deftp

@deftp Subr tc7_subr_1
C function of one argument.
@end deftp

@deftp Subr tc7_cxr
These subrs are handled specially.  If inexact numbers are enabled, the
@code{CDR} should be a function which takes and returns type
@code{double}.  Conversions are handled in the interpreter.

@code{floor}, @code{ceiling}, @code{truncate}, @code{round},
@code{$sqrt}, @code{$abs}, @code{$exp}, @code{$log}, @code{$sin},
@code{$cos}, @code{$tan}, @code{$asin}, @code{$acos}, @code{$atan},
@code{$sinh}, @code{$cosh}, @code{$tanh}, @code{$asinh}, @code{$acosh},
@code{$atanh}, and @code{exact->inexact} are defined this way.

If the @code{CDR} is @code{0} (@code{NULL}), the name string of the
procedure is used to control traversal of its list structure argument.

@code{car}, @code{cdr}, @code{caar}, @code{cadr}, @code{cdar},
@code{cddr}, @code{caaar}, @code{caadr}, @code{cadar}, @code{caddr},
@code{cdaar}, @code{cdadr}, @code{cddar}, @code{cdddr}, @code{caaaar},
@code{caaadr}, @code{caadar}, @code{caaddr}, @code{cadaar},
@code{cadadr}, @code{caddar}, @code{cadddr}, @code{cdaaar},
@code{cdaadr}, @code{cdadar}, @code{cdaddr}, @code{cddaar},
@code{cddadr}, @code{cdddar}, and @code{cddddr} are defined this way.
@end deftp

@deftp Subr tc7_subr_3
C function of 3 arguments.
@end deftp

@deftp Subr tc7_subr_2
C function of 2 arguments.
@end deftp

@deftp Subr tc7_rpsubr
transitive relational predicate C function of 2 arguments.  The C
function should return either @code{BOOL_T} or @code{BOOL_F}.
@end deftp

@deftp Subr tc7_subr_1o
C function of one optional argument.  If the optional argument is not
present, @code{UNDEFINED} is passed in its place.
@end deftp

@deftp Subr tc7_subr_2o
C function of 1 required and 1 optional argument.  If the optional
argument is not present, @code{UNDEFINED} is passed in its place.
@end deftp

@deftp Subr tc7_lsubr_2
C function of 2 arguments and a list of (rest of) @code{SCM} arguments.
@end deftp

@deftp Subr tc7_lsubr
C function of list of @code{SCM} arguments.
@end deftp

@noindent
A @dfn{ptob} is a port object, capable of delivering or accepting
characters.  @xref{Ports, , , r4rs, Revised(4) Report on the Algorithmic
Language Scheme}.  Unlike the types described so far, new varieties of
ptobs can be defined dynamically (@pxref{Defining Ptobs}).  These are
the initial ptobs:

@deftp ptob tc16_inport
input port.
@end deftp

@deftp ptob tc16_outport
output port.
@end deftp

@deftp ptob tc16_ioport
input-output port.
@end deftp

@deftp ptob tc16_inpipe
input pipe created by @code{popen()}.
@end deftp

@deftp ptob tc16_outpipe
output pipe created by @code{popen()}.
@end deftp

@deftp ptob tc16_strport
String port created by @code{cwos()} or @code{cwis()}.
@end deftp

@deftp ptob tc16_sfport
Software (virtual) port created by @code{mksfpt()} (@pxref{Soft Ports}).
@end deftp

@defmac PORTP x
@defmacx OPPORTP x
@defmacx OPINPORTP x
@defmacx OPOUTPORTP x
@defmacx INPORTP x
@defmacx OUTPORTP x
Returns non-zero if @var{x} is a port, open port, open input-port, open
output-port, input-port, or output-port, respectively.
@end defmac

@defmac OPENP x
@defmacx CLOSEDP x
Returns non-zero if port @var{x} is open or closed, respectively.
@end defmac

@defmac STREAM x
Returns the @code{FILE *} stream for port @var{x}.
@end defmac

@noindent
Ports which are particularly well behaved are called @dfn{fport}s.
Advanced operations like @code{file-position} and @code{reopen-file}
only work for fports.

@defmac FPORTP x
@defmacx OPFPORTP x
@defmacx OPINFPORTP x
@defmacx OPOUTFPORTP x
Returns non-zero if @var{x} is a port, open port, open input-port, or
open output-port, respectively.
@end defmac

@noindent
A @dfn{smob} is a miscellaneous datatype.  The type code and GCMARK bit
occupy the lower order 16 bits of the @code{CAR} half of the cell.  The
rest of the @code{CAR} can be used for sub-type or other information.
The @code{CDR} contains data of size long and is often a pointer to
allocated memory.

@noindent
Like ptobs, new varieties of smobs can be defined dynamically
(@pxref{Defining Smobs}).  These are the initial smobs:

@deftp smob tc_free_cell
unused cell on the freelist.
@end deftp

@deftp smob tc16_flo
single-precision float.

Inexact number data types are subtypes of type @code{tc16_flo}.  If the
sub-type is:

@enumerate 0
@item
a single precision float is contained in the @code{CDR}.
@item
@code{CDR} is a pointer to a @code{malloc}ed double.
@end enumerate
@enumerate 3
@item
@code{CDR} is a pointer to a @code{malloc}ed pair of doubles.
@end enumerate

@deftp smob tc_dblr
double-precision float.
@end deftp

@deftp smob tc_dblc
double-precision complex.
@end deftp
@end deftp

@deftp smob tc16_bigpos
@deftpx 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 @code{malloc}ed array
of type @code{BIGDIG} which must be an unsigned integral type with size
smaller than @code{long}.  @code{BIGRAD} is the radix associated with
@code{BIGDIG}.
@end deftp

@deftp smob tc16_promise
made by DELAY.  @xref{Control features, , , r4rs, Revised(4) Scheme}.
@end deftp

@deftp smob tc16_arbiter
synchronization object.  @xref{Process Synchronization}.
@end deftp

@deftp smob tc16_macro
macro expanding function.  @xref{Low Level Syntactic Hooks}.
@end deftp

@deftp smob tc16_array
multi-dimensional array.  @xref{Arrays}.

This type implements both conventional arrays (those with arbitrary data
as elements @pxref{Conventional Arrays}) and uniform arrays (those with
elements of a uniform type @pxref{Uniform Array}).

Conventional Arrays have a pointer to a vector for their @code{CDR}.
Uniform Arrays have a pointer to a Uniform Vector type (string, bvect,
ivect, uvect, fvect, dvect, or cvect) in their @code{CDR}.
@end deftp


@node Data Type Representations,  , Cells, Data Types
@subsection Data Type Representations

@format
@r{IMMEDIATE:      B,D,E,F=data bit, C=flag code, P=pointer address bit}
@t{        ................................
inum    BBBBBBBBBBBBBBBBBBBBBBBBBBBBBB10
ichr    BBBBBBBBBBBBBBBBBBBBBBBB11110100
iflag                   CCCCCCC101110100
isym                    CCCCCCC001110100}
@r{        IMCAR:  only in car of evaluated code, cdr has cell's GC bit}
@t{ispcsym                 000CCCC00CCCC100
iloc    0DDDDDDDDDDDDDDDEFFFFFFF11111100
pointer PPPPPPPPPPPPPPPPPPPPPPPPPPPPP000
gloc    PPPPPPPPPPPPPPPPPPPPPPPPPPPPP001}

@r{   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:}
@t{cons    ..........SCM car..............0  ...........SCM cdr.............G
closure ..........SCM code...........011  ...........SCM env.............G
        HEADERs:
ssymbol .........long length....G0000101  ..........char *chars...........
msymbol .........long length....G0000111  ..........char *chars...........
string  .........long length....G0001101  ..........char *chars...........
vector  .........long length....G0001111  ...........SCM **elts...........
bvect   .........long length....G0010101  ..........long *words...........
 spare                          G0010111
ivect   .........long length....G0011101  ..........long *words...........
uvect   .........long length....G0011111  ......unsigned long *words......
 spare                          G0100101
 spare                          G0100111
fvect   .........long length....G0101101  .........float *words...........
dvect   .........long length....G0101111  ........double *words...........
cvect   .........long length....G0110101  ........double *words...........

contin  .........long length....G0111101  .............*regs..............
cclo    .........long length....G0111111  ...........SCM **elts...........}
@r{        SUBRs:}
@t{ 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_2n..........int hpoff.....01110111  ...........SCM (*f)()...........
rpsubr  ..........int hpoff.....01111101  ...........SCM (*f)()...........}
@r{                        PTOBs:}
@t{   port            0bwroxxxxxxxxG1110111  ..........FILE *stream..........
 socket ttttttt    00001xxxxxxxxG1110111  ..........FILE *stream..........
 inport uuuuuuuuuuU00011xxxxxxxxG1110111  ..........FILE *stream..........
outport 0000000000000101xxxxxxxxG1110111  ..........FILE *stream..........
 ioport uuuuuuuuuuU00111xxxxxxxxG1110111  ..........FILE *stream..........
fport              00   00000000G1110111  ..........FILE *stream..........
pipe               00   00000001G1110111  ..........FILE *stream..........
strport            00   00000010G1110111  ..........FILE *stream..........
sfport             00   00000011G1110111  ..........FILE *stream..........}
@r{                        SMOBs:}
@t{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..............}
@end format

@node Operations, Improvements To Make, Data Types, Internals
@section Operations

@menu
* Garbage Collection::          Automatically reclaims unused storage
* Signals::                     
* C Macros::                    
* Changing Scm::                How to @emph{really} screw it up
* Defining Subrs::              
* Defining Smobs::              
* Defining Ptobs::              
* Calling Scheme From C::       
* Continuations::               
* Evaluation::                  Why SCM is fast
@end menu

@node Garbage Collection, Signals, Operations, Operations
@subsection Garbage Collection

The garbage collector is in the latter half of @file{sys.c}.  Immediates
always appear as parts of other objects, so they are not subject to
explicit garbage collection.  There is a heap (composed of heap
segments) in which all cells reside.  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.

To garbage collect, first certain protected objects are marked (such as
symhash).  Then the stack (and marked continuations) are traversed.
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.  If the stack is word rather than longword aligned
@code{(#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.

The heap is then swept.  If a type-header cell pointing to malloc
space is collected the malloc object is then freed.  If the type
header of smob is collected, the smob's free procedure is called to
free its storage.

@node Signals, C Macros, Garbage Collection, Operations
@subsection Signals

@defun init_signals
(in @file{scm.c}) initializes handlers for @code{SIGINT} and
@code{SIGALRM} if they are supported by the C implementation.  All of
the signal handlers immediately reestablish themselves by a call to
@code{signal()}.
@end defun

@defun int_signal sig
@defunx alrm_signal sig
The low level handlers for @code{SIGINT} and @code{SIGALRM}.
@end defun

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.  @code{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 @code{DEFER_INTS} and @code{ALLOW_INTS}.

@defmac DEFER_INTS
sets the global variable @code{ints_disabled} to 1.  If an interrupt
occurs during a time when @code{ints_disabled} is 1 one of the global
variables @code{sig_deferred} or @code{alrm_deferred} is set to 1 and
the handler returns.

@defmacx ALLOW_INTS
Checks the deferred variables and if set the appropriate handler is
called.

Calls to @code{DEFER_INTS} can not be nested.  An @code{ALLOW_INTS} must
happen before another @code{DEFER_INTS} can be done.  In order to check
that this constraint is satisfied @code{#define CAREFUL_INTS} in
@file{scmfig.h}.
@end defmac

@node C Macros, Changing Scm, Signals, Operations
@subsection C Macros


@defmac ASSERT cond arg pos subr
signals an error if the expression (@var{cond}) is 0.  @var{arg} is the
offending object, @var{subr} is the string naming the subr, and
@var{pos} indicates the position or type of error.  @var{pos} can be one
of

@itemize @bullet
@item @code{ARGn} @i{(> 5 or unknown ARG number)}
@item @code{ARG1}
@item @code{ARG2}
@item @code{ARG3}
@item @code{ARG4}
@item @code{ARG5}
@item @code{WNA} @i{(wrong number of args)}
@item @code{OVFLOW}
@item @code{OUTOFRANGE}
@item @code{NALLOC}
@item @code{EXIT}
@item @code{HUP_SIGNAL}
@item @code{INT_SIGNAL}
@item @code{FPE_SIGNAL}
@item @code{BUS_SIGNAL}
@item @code{SEGV_SIGNAL}
@item @code{ALRM_SIGNAL}
@item a C string @code{(char *)}
@end itemize

Error checking is not done by @code{ASSERT} if the flag @code{RECKLESS}
is defined.  An error condition can still be signaled in this case with
a call to @code{wta(arg, pos, subr)}.
@end defmac

@defmac ASRTGO cond label
@code{goto} @var{label} if the expression (@var{cond}) is 0.  Like
@code{ASSERT}, @code{ASRTGO} does is not active if the flag
@code{RECKLESS} is defined.
@end defmac


@node Changing Scm, Defining Subrs, C Macros, Operations
@subsection Changing Scm

@noindent
When writing C-code for SCM, a precaution is recommended.  If your
routine allocates a non-cons cell which will @emph{not} be incorporated
into a @code{SCM} object which is returned, you need to make sure that a
@code{SCM} variable in your routine points to that cell as long as part
of it might be referenced by your code.

@noindent
In order to make sure this @code{SCM} variable does not get optimized
out you can put this assignment after its last possible use:

@example
SCM_dummy1 = @i{foo};
@end example

@noindent
or put this assignment somewhere in your routine:

@example
SCM_dummy1 = (SCM) &@i{foo};
@end example

@noindent
@code{SCM_dummy} variables are not currently defined.  Passing the
address of the local @code{SCM} variable to @emph{any} procedure also
protects it.

@noindent
Also, if you maintain a static pointer to some (non-immediate)
@code{SCM} object, you must either make your pointer be the value cell
of a symbol (see @code{errobj} for an example) or make your pointer be
one of the @code{sys_protects} (see @code{symhash} for an example).  The
former method is prefered since it does not require any changes to the
SCM distribution.

@noindent
To add a C routine to scm:

@enumerate
@item
choose the appropriate subr type from the type list.
@item
write the code and put into @file{scm.c}.
@item
add a @code{make_subr} or @code{make_gsubr} call to @code{init_scm}.  Or
put an entry into the appropriate @code{iproc} structure.
@end enumerate

To add a package of new procedures to scm (see @file{crs.c} for
example):

@enumerate
@item
create a new C file (@file{@i{foo}.c}).
@item
at the front of @file{@i{foo}.c} put declarations for strings for your
procedure names.

@example
static char s_twiddle_bits[]="twiddle-bits!";
static char s_bitsp[]="bits?";
@end example

@item
choose the appropriate subr types from the type list in @file{code.doc}.
@item
write the code for the procedures and put into @file{@i{foo}.c}
@item
create one @code{iproc} structure for each subr type used in @file{@i{foo}.c}

@example
static iproc subr3s[]= @{
        @{s_twiddle-bits,twiddle-bits@},
        @{s_bitsp,bitsp@},
        @{0,0@} @};
@end example

@item
create an @code{init_@i{<name of file>}} routine at the end of the file
which calls @code{init_iprocs} with the correct type for each of the
@code{iproc}s created in step 5.

@example
void init_@i{foo}()
@{
  init_iprocs(subr1s, tc7_subr_1);
  init_iprocs(subr3s, tc7_subr_3);
@}
@end example

If your package needs to have a @dfn{finalization} routine called to
free up storage, close files, etc, then also have a line in
@code{init_@i{foo}} like:

@example
add_final(final_@i{foo});
@end example

@code{final_@i{foo}} should be a (void) procedure of no arguments.  The
finals will be called in opposite order from their definition.

The line:

@example
add_feature("@i{foo}");
@end example

will append a symbol @code{'@i{foo}} to the (list) value of
@code{*features*}.
@item
put any scheme code which needs to be run as part of your package into
@file{I@i{foo}.scm}.
@item
put an @code{if} into @file{Init.scm} which loads @file{I@i{foo}.scm} if
your package is included:

@example
(if (defined? twiddle-bits!)
    (load (in-vicinity (implementation-vicinity)
                       "I@i{foo}"
                       (scheme-file-suffix))))
@end example

or use @code{(provided? '@i{foo})} instead of @code{(defined?
twiddle-bits!)} if you have added the feature.
@item
put documentation of the new procedures into @file{@i{foo}.doc}
@item
add lines to your @file{Makefile} to compile and link SCM with your
object file.  Add a @code{init_@i{foo}\(\)\;} to the @code{INITS=@dots{}}
line at the beginning of the makefile.
@end enumerate

@noindent
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.

@enumerate
@item
define a new @code{MAKISYM} in @file{scm.h} and increment
@code{NUM_ISYMS}.
@item
add a string with the new name in the corresponding place in
@code{isymnames} in @file{repl.c}.
@item
add @code{case:} clause to @code{ceval()} near @code{i_quasiquote} (in
@file{eval.c}).
@end enumerate

@noindent
New syntax can now be added without recompiling SCM by the use of the
@code{procedure->syntax}, @code{procedure->macro},
@code{procedure->memoizing-macro}, and @code{defmacro}.  For details,
@xref{Syntax Extensions}.

@node Defining Subrs, Defining Smobs, Changing Scm, Operations
@subsection Defining Subrs

@noindent
If @dfn{CCLO} is @code{#define}d when compiling, the compiled closure
feature will be enabled.  It is automatically enabled if dynamic linking
is enabled.

@noindent
The SCM interpreter directly recognizes subrs taking small numbers of
arguments.  In order to create subrs taking larger numbers of arguments
use:

@defun make_gsubr name req opt rest fcn
returns a cclo (compiled closure) object of name @code{char *}
@var{name} which takes @code{int} @var{req} required arguments,
@code{int} @var{opt} optional arguments, and a list of rest arguments if
@code{int} @var{rest} is 1 (0 for not).

@code{SCM (*fcn)()} is a pointer to a C function to do the work.

The C function will always be called with @var{req} + @var{opt} +
@var{rest} arguments, optional arguments not supplied will be passed
@code{UNDEFINED}.  An error will be signaled if the subr is called with
too many or too few arguments.  Currently a total of 10 arguments may be
specified, but increasing this limit should not be difficult.

@example
/* A silly example, taking 2 required args,
   1 optional, and a list of rest args */

SCM gsubr_21l(req1,req2,opt,rst)
     SCM req1,req2,opt,rst;
@{
  lputs("gsubr-2-1-l:\n req1: ", cur_outp);
  display(req1,cur_outp);
  lputs("\n req2: ", cur_outp);
  display(req2,cur_outp);
  lputs("\n opt: ", cur_outp);
  display(opt,cur_outp);
  lputs("\n rest: ", cur_outp);
  display(rst,cur_outp);
  newline(cur_outp);
  return UNSPECIFIED;
@}

void init_gsubr211()
@{
  make_gsubr("gsubr-2-1-l", 2, 1, 1, gsubr_21l);
@}
@end example
@end defun

@node Defining Smobs, Defining Ptobs, Defining Subrs, Operations
@subsection Defining Smobs

@noindent
Here is an example of how to add a new type named @code{@i{foo}} to SCM.
The following lines need to be added to your code:

@table @code
@item long tc16_@i{foo};
The type code which will be used to identify the new type.
@item static smobfuns @i{foo}smob = @{mark@i{foo},free@i{foo},print@i{foo},equalp@i{foo}@};
smobfuns is a structure composed of 4 functions:

@example
typedef struct @{
  SCM   (*mark)P((SCM));
  sizet (*free)P((CELLPTR));
  int   (*print)P((SCM exp, SCM port, int writing));
  SCM   (*equalp)P((SCM, SCM));
@} smobfuns;
@end example

@table @code
@item smob.mark
is a function of one argument of type @code{SCM} (the cell to mark) and
returns type @code{SCM} which will then be marked.  If no further
objects need to be marked then return an immediate object such as
@code{BOOL_F}.  2 functions are provided:

@table @code
@item markcdr(ptr)
which marks the current cell and returns @code{CDR(ptr)}.
@item mark0(ptr)
which marks the current cell and returns @code{BOOL_F}.
@end table

@item smob.free
is a function of one argument of type @code{CELLPTR} (the cell to
collected) and returns type @code{sizet} which is the number of
@code{malloc}ed bytes which were freed.  @code{Smob.free} should free
any @code{malloc}ed storage associated with this object.  The function
free0(ptr) is provided which does not free any storage and returns 0.
@item smob.print
is 0 or a function of 3 arguments.  The first, of type @code{SCM}, is
the smob object.  The second, of type @code{SCM}, is the stream on which
to write the result.  The third, of type int, is 1 if the object should
be @code{write}n, 0 if it should be @code{display}ed.  This function
should return non-zero if it printed, and zero otherwise (in which case
a hexadecimal number will be printed).
@item smob.equalp
is 0 or a function of 2 @code{SCM} arguments.  Both of these arguments
will be of type @code{tc16@i{foo}}.  This function should return
@code{BOOL_T} if the smobs are equal, @code{BOOL_F} if they are not.  If
@code{smob.equalp} is 0, @code{equal?} will return @code{BOOL_F} if they
are not @code{eq?}.
@end table

@item tc16_@i{foo} = newsmob(&@i{foo}smob);
Allocates the new type with the functions from @code{@i{foo}smob}.  This
line goes in an @code{init_} routine.
@end table

@noindent
Promises and macros in @file{eval.c} and arbiters in @file{repl.c}
provide examples of SMOBs.  There are a maximum of 256 SMOBs.

@node Defining Ptobs, Calling Scheme From C, Defining Smobs, Operations
@subsection Defining Ptobs

@noindent
@dfn{ptob}s are similar to smobs but define new types of port to which
SCM procedures can read or write.  The following functions are defined
in the @code{ptobfuns}:

@example
typedef struct @{
  SCM   (*mark)P((SCM ptr));
  int   (*free)P((FILE *p));
  int   (*print)P((SCM exp, SCM port, int writing));
  SCM   (*equalp)P((SCM, SCM));
  int   (*fputc)P((int c, FILE *p));
  int   (*fputs)P((char *s, FILE *p));
  sizet (*fwrite)P((char *s, sizet siz, sizet num, FILE *p));
  int   (*fflush)P((FILE *stream));
  int   (*fgetc)P((FILE *p));
  int   (*fclose)P((FILE *p));
@} ptobfuns;
@end example

@noindent
The @code{.free} component to the structure takes a @code{FILE *} or
other C construct as its argument, unlike @code{.free} in a smob, which
takes the whole smob cell.  Often, @code{.free} and @code{.fclose} can be
the same function.  See @code{fptob} and @code{pipob} in @file{sys.c}
for examples of how to define ptobs.

@node Calling Scheme From C, Continuations, Defining Ptobs, Operations
@subsection Calling Scheme From C

@noindent
To use SCM as a whole from another program call @code{init_scm} or
@code{run_scm} as is done in @code{main()} in @file{scm.c}.

@noindent
In order to call indivdual Scheme procedures from C code more is
required; SCM's storage system needs to be initialized.  The simplest
way to do this for a statically linked single-thread program is to:

@enumerate
@item
make a SCM procedure which calls your code's startup routine.
@item
use the @code{#define RTL} flag when compiling @file{scm.c} to elide
SCM's @code{main()}.
@item
In your @code{main()}, call @code{run_scm} with arguments (@code{argc}
and @code{argv}) to invoke your code's startup routine.
@item
link your code with SCM at compile time.
@end enumerate

@noindent
For a dynamically linked single-thread program:

@enumerate
@item
make an @code{init_} procedure for your code which will set up any Scheme
definitions you need and then call your startup routine
(@pxref{Changing Scm}).
@item
Start SCM with command line arguments to dynamically link your code.
After your module is linked, the @code{init_} procedure will be called, and
hence your startup routine.
@end enumerate

@noindent
Now use @code{apply} (and perhaps @code{intern}) to call Scheme
procedures from your C code.  For example:

@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);
@end example

@noindent
SCM now has routines to make calling back to Scheme procedures easier:

@deftypefun int scm_ldfile (char *@var{file})
Loads the Scheme source file @var{file}.  Returns 0 if successful, non-0
if not.  This function is used to load SCM's initialization file
@file{Init.scm}.
@end deftypefun

@deftypefun int scm_ldprog (char *@var{file})
Loads the Scheme source file @code{(in-vicinity (program-vicinity)
@var{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.  @code{program-vicinity} is the
directory from which the calling code was loaded (@pxref{Vicinity, , ,
slib, SLIB}).
@end deftypefun

@deftypefun SCM scm_evstr (char *@var{str})
Returns the result of reading an expression from @var{str} and
evaluating it.
@end deftypefun

@deftypefun void scm_ldstr (char *@var{str})
Reads and evaluates all the expressions from @var{str}.
@end deftypefun

@noindent
If you wish to catch errors during execution of Scheme code, then you
can use a wrapper like this for your Scheme procedures:

@example
(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))
@end example

@noindent
Calls to procedures so wrapped will return even if an error occurs.

@node Continuations, Evaluation, Calling Scheme From C, Operations
@subsection Continuations

@noindent
The scm procedure call-with-current-continuation calls it's argument
with an object of type @code{contin}.

@noindent
If @code{CHEAP_CONTINUATIONS} is #defined (in @file{scmfig.h}) the
contin just contains a jmp_buf.  When the contin is applied, a longjmp
of the jmp_buf is done.

@noindent
If @code{CHEAP_CONTINUATIONS} is not #defined the contin contains the
jmp_buf and a copy of the C stack between the call_cc stack frame and
BASE(rootcont).  When the contin is applied:

@itemize
@item
the stack is grown larger than the saved stack, if neccessary.
@item
the saved stack is copied back into it's original position.
@item
longjmp of the jmp_buf is called.
@end itemize

@noindent
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 @code{CHEAP_CONTINUATIONS} in
@file{scmfig.h}.

@node Evaluation,  , Continuations, Operations
@subsection Evaluation

@defvar symhash
Top level symbol values are stored in the @code{symhash} table.
@code{symhash} is an array of lists of ISYMs and pairs of symbols and
values.
@end defvar

@deftp 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.
@end deftp

@deftp 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 @code{CAR}
position and the GCmark is in the @code{CDR}, there is no conflict.
@end deftp

@noindent
If the compile FLAG @code{CAUTIOUS} is #defined then the number of
arguments is always checked for application of closures.  If the
compile FLAG @code{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.

@defmac EVAL expression env
@defmacx SIDEVAL expression env
@code{EVAL} Returns the result of evaluating @var{expression} in
@var{env}.  @code{SIDEVAL} evaluates @var{expression} in @var{env} when
the value of the expression is not used.

Both of these macros alter the list structure of @var{expression} as it
is memoized and hence should be used only when it is known that
@var{expression} will not be referenced again.  The C function
@code{eval} is safe from this problem.
@end defmac

@deftypefun SCM eval (SCM @var{expression})
Returns the result of evaluating @var{expression} in the top-level
environment.  @code{eval} copies @code{expression} so that memoization
does not modify @code{expression}.
@end deftypefun

@node Improvements To Make, Finishing Dynamic Linking, Operations, Internals
@section Improvements To Make

@itemize @bullet
@item
Prefix and make more uniform all C function, variable, and constant
names.  Provide a file full of #define's to provide backward
compatability.
@item
@code{lgcd()} @emph{needs} to generate at most one bignum, but currently
generates more.
@item
@code{divide()} could use shifts instead of multiply and divide when
scaling.
@item
If an open fails because there are no unused file handles, GC should
be done so that file handles which are no longer used can be
collected.
@item
If the symhash array is specially marked in garbage collection, msymbols
with value @code{UNDEFINED} which have no pointers to them can be
collected.  In Maclisp this was called @code{gctwa}.
@item
Compaction could be done to @code{malloc}ed objects by freeing and
reallocing all the malloc objects encountered in a scan of the heap.
Whether compactions would actually occur is system depenedent.
@item
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.
@item
lookupcar in @file{eval.c} should @emph{not} memoize (to @code{ILOC}s)
when it retrieves environments deeper or longer than 4095.  The values
can still be retrieved (albeit slowly), but an @code{ILOC} should not be
made.  The @code{MEMOIZE_LOCALS} flag could then be flushed.
@item
The @code{must-} or @code{make-} routines need some sort of C macros or
conditionalization so that they check:

@itemize @bullet
@item
that the @code{LENGTH} field fits into a @code{size_t} (as is checked
now) for platforms with @code{(sizeof(size_t) < sizeof(SCM))}.
@item
that the @code{LENGTH} field fits into 24 (or 56) bits on machines where
@code{size_t} is 32 bits or more.
@end itemize

This is trickier than it first looks because the must_malloc() routine
is also used for allocating heap segments, which do not have the
@code{LENGTH} field restriction.  Putting the 24 bit test into
@code{must_malloc()} should be tested for speed impact.
@end itemize

@node Finishing Dynamic Linking,  , Improvements To Make, Internals
@section Finishing Dynamic Linking

@noindent
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.

@subsubheading VMS

@noindent
George Carrette (gjc@@mitech.com) outlines how to dynamically link on
VMS.  There is already some code in @file{dynl.c} to do this, but
someone with a VMS system needs to finish and debug it.

@enumerate
@item
Say you have this @file{main.c} program:

@format
@t{main()
@{init_lisp();
 lisp_repl();@}}
@end format

@item
and you have your lisp in files @file{repl.c}, @file{gc.c},
@code{eval.c} and there are some toplevel non-static variables in use
called @code{the_heap}, @code{the_environment}, and some read-only
toplevel structures, such as @code{the_subr_table}.

@format
@t{$ LINK/SHARE=LISPRTL.EXE/DEBUG REPL.OBJ,GC.OBJ,EVAL.OBJ,LISPRTL.OPT/OPT}
@end format

@item
where @file{LISPRTL.OPT} must contain at least this:

@format
@t{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}
@end format

@emph{Notice:} The @dfn{psect} (Program Section) attributes.
@table @code
@item LCL
means to keep the name local to the shared library.  You almost always
want to do that for a good clean library.
@item SHR,NOWRT
means shared-read-only.  Which is the default for code, and is also good
for efficiency of some data structures.
@item NOSHR,LCL
is what you want for everything else.
@end table

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,

@format
@t{$SEARCH/OUT=LISPRTL.LOSERS LISPRTL.MAP  ",  SHR,NOEXE,  RD,  WRT"}
@end format

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.

@item
@noindent
Now MAIN.EXE would be linked thusly:

@format
@t{$ DEFINE LISPRTL USER$DISK:[JAFFER]LISPRTL.EXE

$LINK MAIN.OBJ,SYS$INPUT:/OPT
 SYS$LIBRARY:VAXCRTL/SHARE
 LISPRTL/SHARE}
@end format

Note the definition of the @code{LISPRTL} logical name.  Without such a
definition you will need to copy @file{LISPRTL.EXE} over to
@file{SYS$SHARE:} (aka @file{SYS$LIBRARY:}) in order to invoke the main
program once it is linked.

@item
Now say you have a file of optional subrs, @file{MYSUBRS.C}.  And there
is a routine @code{INIT_MYSUBRS} that must be called before using it.

@format
@t{$ CC MYSUBRS.C
$ LINK/SHARE=MYSUBRS.EXE MYSUBRS.OBJ,SYS$INPUT:/OPT
  SYS$LIBRARY:VAXCRTL/SHARE
  LISPRTL/SHARE
  UNIVERSAL=INIT_MYSUBRS}
@end format

Ok.  Another hint is that you can avoid having to add the @code{PSECT}
declaration of @code{NOSHR,LCL} by declaring variables @code{status} in
the C language source.  That works great for most things.

@item
Then the dynamic loader would have to do this:

@format
@t{@{void (*init_fcn)();
 long retval;
 retval = lib$find_image_symbol("MYSUBRS","INIT_MYSUBRS",&init_fcn,
                                "SYS$DISK:[].EXE");
 if (retval != SS$_NORMAL) error(@dots{});
 (*init_fcn)();@}}
@end format

But of course all string arguments must be @code{(struct dsc$descriptor
*)} and the last argument is optional if @code{MYSUBRS} is defined as a
logical name or if @file{MYSUBRS.EXE} has been copied over to
@file{SYS$SHARE}.  The other consideration is that you will want to turn
off @key{C-c} or other interrupt handling while you are inside most
@code{lib$} calls.

As far as the generation of all the @code{UNIVERSAL=@dots{}}
declarations.  Well, you could do well to have that automatically
generated from the public @file{LISPRTL.H} file, of course.

VMS has a good manual called the @cite{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 @code{LISPRTL} you probably don't need that hair.

One fancier option that is useful under VMS for @file{LISPLIB.EXE} is to
define all your exported procedures through an @dfn{call vector} instead
of having them just be pointers into random places in the image, which
is what you get by using @code{UNIVERSAL}.

If you set up the call vector thing correctly it will allow you to
modify and relink @file{LISPLIB.EXE} without having to relink programs
that have been linked against it.
@end enumerate

@subsubheading Windows NT
@noindent
George Carrette (gjc@@mitech.com) outlines how to dynamically link on
Windows NT:

@itemize @bullet
@item
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)

@format
@t{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)}
@end format

@item
The @file{LISPDEF.DEF} file has this:

@format
@t{LIBRARY lisplib
EXPORT
 init_lisp
 init_repl}
@end format

@item
And @file{MAIN.EXE} using:

@format
@t{CLINK = $(link) $(ldebug) $(conflags) -out:$*.exe $** $(conlibsdll)

MAIN.EXE : MAIN.OBJ LISPLIB.LIB
 $(CLINK)}
@end format

@item
And @file{MYSUBRS.DLL} is produced using:

@format
@t{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)}
@end format

@item
Where @file{MYSUBRS.DEF} has

@format
@t{LIBRARY mysubrs
EXPORT
 INIT_MYSUBRS}
@end format

@item
And the dynamic loader looks something like this, calling the two
procedures @code{LoadLibrary} and @code{GetProcAddress}.

@format
@t{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);@}}
@end format

@item
@emph{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.

@item
@emph{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.
@end itemize


@node Procedure and Macro Index, Variable Index, Internals, Top
@unnumbered Procedure and Macro Index

This is an alphabetical list of all the procedures and macros in SCM.

@printindex fn

@node Variable Index, Type Index, Procedure and Macro Index, Top
@unnumbered Variable Index

This is an alphabetical list of all the global variables in SCM.

@printindex vr

@node Type Index,  , Variable Index, Top
@unnumbered Type Index

This is an alphabetical list of all the data types in SCM.

@printindex tp

@contents
@bye
