s48-refman/scheme48.info-2

This is scheme48.info, produced by makeinfo version 6.7 from
scheme48.texi.

This manual is for Scheme48 version 1.3.

   Copyright (C) 2004, 2005, 2006 Taylor Campbell.  All rights reserved.

   This manual includes material derived from works bearing the
following notice:

   Copyright (C) 1993-2005 Richard Kelsey, Jonathan Rees, and Mike
Sperber.  All rights reserved.

     Redistribution and use in source and binary forms, with or without
     modification, are permitted provided that the following conditions
     are met:

        * Redistributions of source code must retain the above copyright
          notice, this list of conditions and the following disclaimer.

        * Redistributions in binary form must reproduce the above
          copyright notice, this list of conditions and the following
          disclaimer in the documentation and/or other materials
          provided with the distribution.

        * The name of the authors may not be used to endorse or promote
          products derived from this software without specific prior
          written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Scheme48: (scheme48).	Nearly complete reference manual for version 1.3
END-INFO-DIR-ENTRY



File: scheme48.info,  Node: Common-Lisp-style formatting,  Next: Library utilities,  Prev: TCP & UDP sockets,  Up: Libraries

6.7 Common-Lisp-style formatting
================================

Scheme48 provides a simple Common-Lisp-style 'format' facility in the
'formats' structure.  It does not provide nearly as much functionality
as Common Lisp, however: the considerable complexity of Common Lisp's
'format' was deliberately avoided because it was deemed inconsistent
with Scheme48's design goals.  Scheme48's 'format' is suitable for most
simple purposes, anyhow.

 -- procedure: format port control-string argument ... --> unspecified
          or string
     Prints CONTROL-STRING to PORT.  If, anywhere in CONTROL-STRING, the
     character '~' (tilde) occurs, the following character determines
     what to print in the place of the tilde and following character.
     Some formatting directives consume arguments from ARGUMENT ....
     Formatting directive characters are case-insensitive.  If PORT is
     '#t', the output is printed to to the value of
     '(current-output-port)'; if PORT is false, the output is collected
     in a string and returned.

     The complete list of formatting directives:

     '~~'
          Prints a single '~' (tilde), and does not consume an argument.

     '~A'
          Consumes and prints the first remaining argument with
          'display'.  ('A'ny)

     '~D'
          Consumes and prints the first remaining argument as a decimal
          number using 'number->string'.  ('D'ecimal)

     '~S'
          Consumes and prints the first remaining argument with 'write'.
          ('S'-expression)

     '~%'
          Prints a newline with 'newline'.

     '~&'
          Prints a newline with 'newline', unless it can be determined
          that a newline was immediately previously printed to PORT
          (*note I/O extensions::).

     '~?'
          Recursively formats.  The first remaining argument is consumed
          and must be another control string; the argument directly
          thereafter is also consumed, and it must be a list of
          arguments corresponding with that control string.  The control
          string is formatted with those arguments using 'format'.

     'Format' examples:

          (format #t "Hello, ~A!~%" "world")
              -| Hello, world!
              -|

          (format #t "Hello~?~S~%" "~A world" '(#\,) '!)
              -| Hello, world!
              -|

          (format #f "~A~A ~A." "cH" "uMBLE" "spuZz")
              => "cHuMBLE spuZz."

          (let ((x 10) (y .1))
            (format #t "x: ~D~%~&y: ~D~%~&" x y))
              -| x: 10
              -| y: .1


File: scheme48.info,  Node: Library utilities,  Prev: Common-Lisp-style formatting,  Up: Libraries

6.8 Library utilities
=====================

Scheme48 provides various miscellaneous library utilities for common
general-purpose tasks.

6.8.1 Destructuring
-------------------

The 'destructuring' structure exports a form for destructuring
S-expressions.

 -- syntax: destructure ((pattern value) ...) body
     For each '(PATTERN VALUE)' pair, binds every name in PATTERN to the
     corresponding location in the S-expression VALUE.  For example,

          (destructure (((x . y) (cons 5 3))
                        ((#(a b) c) '(#((1 2) 3) (4 5))))
            BODY)

     binds X to '5', Y to '3', A to '(1 2)', B to '3', and C to '(4 5)',
     in BODY.

6.8.2 Pretty-printing
---------------------

The 'pp' structure exports a simple pretty-printer.

 -- procedure: p object [port] --> unspecified
 -- procedure: pretty-print object port position --> unspecified
     'P' is a convenient alias for 'pretty-print'; it passes 0 for
     POSITION and the value of '(current-output-port)' if PORT is not
     passed.  'Pretty-print' pretty-prints OBJECT to PORT, using a left
     margin of POSITION.  For example:

          (p '(define (fact n)
                (let loop ((p 1) (c 1))
                  (if (> c n) p (loop (* p c) (+ c 1))))))
              -| (define (fact n)
              -|   (let loop ((p 1) (c 1))
              -|     (if (> c n)
              -|         p
              -|         (loop (* p c) (+ c 1)))))

   The pretty-printer is somewhat extensible as well:

 -- procedure: define-indentation name count --> unspecified
     Sets the number of subforms to be indented past NAME in
     pretty-printed output to be COUNT.  For example:

          (define-indentation 'frobozz 3)
          (p '(frobozz (foo bar baz quux zot) (zot quux baz bar foo)
                       (mumble frotz gargle eek) (froomble zargle hrumph)))
              -| (frobozz (foo bar baz quux zot)
              -|          (zot quux baz bar foo)
              -|          (mumble frotz gargle eek)
              -|   (froomble zargle hrumph))

6.8.3 Strongly connected graph components
-----------------------------------------

The 'strong' structure exports a routine for finding a list of the
strongly connected components in a graph.

 -- procedure: strongly-connected-components vertices to slot set-slot!
          --> sorted-strong-vertices
     Returns the components of a graph containing vertices from the list
     VERTICES that are strongly connected, in a reversed topologically
     sorted list.  TO should be a procedure of one argument, a vertex,
     that returns a list of all vertices that have an edge to its
     argument.  SLOT & SET-SLOT! should be procedures of one & two
     arguments, respectively, that access & modify arbitrary slots used
     by the algorithm.  The slot for every vertex should initially be
     '#f' before calling 'strongly-connected-components', and the slots
     are reverted to '#f' before 'strongly-connected-components'
     returns.

6.8.4 Nondeterminism
--------------------

The 'nondeterminism' structure provides a simple nondeterministic
ambivalence operator, like McCarthy's 'AMB', and a couple utilities atop
it, built with Scheme's 'call-with-current-continuation'.

 -- procedure: with-nondeterminism thunk --> values
     Initializes the nondeterminism system and calls THUNK; this returns
     the values THUNK returns after then tearing down what was set up.

 -- syntax: either option ... --> value
 -- syntax: one-value exp --> value
 -- syntax: all-values exp --> list
     'Either' evaluates to the value of any one of the options.  It is
     equivalent to McCarthy's 'AMB'.  It may return any number of times.
     'One-value' returns the only value that EXP could produce; it will
     return only once, although it may actually return any number of
     values (if EXP contains a call to 'values').  'All-values' returns
     a list of all of the single values, not multiple values, that EXP
     could nondeterministically evaluate to.

 -- procedure: fail --> does not return
     Signals a nondeterministic failure.  This is invalid outside of a
     'with-nondeterminism'-protected dynamic extent.

6.8.5 Miscellaneous utilities
-----------------------------

The 'big-util' structure exports a variety of miscellaneous utilities.

 -- procedure: concatenate-symbol elt ... --> symbol
     Returns a symbol containing the contents of the sequence ELT ....
     Each ELT may be another symbol, a string, or a number.  Numbers are
     converted to strings in base ten.

 -- procedure: error format-string argument ... --> values (may not
          return)
 -- procedure: breakpoint format-string argument ... --> values (may not
          return)
     'Error' signals an error whose message is formatted by 'format'
     (*note Common-Lisp-style formatting::) with the given formatting
     template string and arguments.  'Breakpoint' signals a breakpoint
     with a message similarly constructed and causes the command
     processor to push a new command level (*note Command levels::).

 -- procedure: atom? x --> boolean
     Returns true if X is not a pair or false if it is.

 -- procedure: neq? x y --> boolean
 -- procedure: n= x y --> boolean
     Negations of the 'eq?' and '=' predicates.

 -- procedure: identity value --> value
 -- procedure: no-op value --> value
     These simply return their arguments.  The difference between them
     is that 'no-op' is guaranteed not to be integrated by the compiler,
     whereas 'identity' may be.

 -- procedure: null-list? object --> boolean
     Returns '#t' if OBJECT is the null list, returns '#f' if OBJECT is
     a pair, or signals an error if OBJECT is neither the null list nor
     a pair.

 -- procedure: reverse! list --> reversed-list
     Returns a list containing the reverse elements of LIST.  Note that
     the original LIST is _not_ reversed; it becomes garbage.
     'Reverse!' simply re-uses its structure.

 -- procedure: memq? object list --> boolean
     Returns '#t' if OBJECT is a member of LIST, as determined by 'eq?';
     or '#f' if not.

 -- procedure: first predicate list --> elt or '#f'
 -- procedure: any predicate list --> elt or '#f'
     'First' returns the first element of LIST that satisfies PREDICATE,
     or '#f' if no element does.  'Any' returns an element of LIST that
     satisfies PREDICATE.  Note that 'any' may choose any element of the
     list, whereas 'first' explicitly returns the _first_ element that
     satisfies PREDICATE.

 -- procedure: any? predicate list --> boolean
 -- procedure: every? predicate list --> boolean
     'Any?' returns '#t' if any element of LIST satisfies PREDICATE, or
     '#f' if none do.  'Every?' returns '#t' if every element of LIST
     satisfies PREDICATE, or '#f' if there exists an element that does
     not.

 -- procedure: filter predicate list --> filtered-list
 -- procedure: filter! predicate list --> filtered-list
     These return a list of all elements in LIST that satisfy PREDICATE.
     'Filter' is not allowed to modify LIST's structure; 'filter!' may,
     however.

 -- procedure: filter-map proc list --> list
     This is a combination of 'filter' and 'map'.  For each element E in
     LIST: if '(PROC E)' returns a true value, that true value is
     collected in the output list.  'Filter-map' does not modify LIST's
     structure.

 -- procedure: remove-duplicates list --> uniquified-list
     Returns a unique list of all elements in LIST; that is, if there
     were any duplicates of any element E in LIST, only a single E will
     occur in the returned list.  'Remove-duplicates' does not modify
     LIST's structure.

 -- procedure: partition-list predicate list --> [satisfied unsatisfied]
 -- procedure: partition-list! predicate list --> [satisfied
          unsatisfied]
     These return two values: a list of all elements in LIST that do
     satisfy PREDICATE and a list of all elements that do not.
     'Partition-list' is not allowed to modify LIST's structure;
     'partition-list!' is.

 -- procedure: delq object list --> list
 -- procedure: delq! object list --> list
     These return a list containing all elements of LIST except for
     OBJECT.  'Delq' is not allowed to modify LIST's structure; 'delq!'
     is.

 -- procedure: delete predicate list --> list
     Returns a list of all elements in LIST that do not satisfy
     PREDICATE.  Note that, despite the lack of exclamation mark in the
     name, this _may_ modify LIST's structure.

 -- procedure: string->immutable-string string --> immutable-string
     Returns an immutable string with STRING's contents.  If STRING is
     already immutable, it is returned; otherwise, an immutable copy is
     returned.

6.8.6 Multiple value binding
----------------------------

The 'receiving' structure exports the 'receive' macro, a convenient
syntax atop R5RS's 'call-with-values'.

 -- syntax: receive formals producer body
     Binds the variables in the lambda parameter list FORMALS to the
     return values of PRODUCER in BODY.

          (receive FORMALS
                   PRODUCER
            BODY)
              ==
          (call-with-values
              (lambda () PRODUCER)
            (lambda FORMALS BODY))

   For sequences of multiple value bindings, the 'mvlet' structure
exports two convenient macros.

 -- syntax: mvlet*
 -- syntax: mvlet
     'Mvlet*' is a multiple-value version of 'let' or a linearly nested
     version of 'receive':

          (mvlet* ((FORMALS_{0} PRODUCER_{0})
                   (FORMALS_{1} PRODUCER_{1})
                   ...)
            BODY)
              ==
          (call-with-values
              (lambda () PRODUCER_{0})
            (lambda FORMALS_{0}
              (call-with-values
                  (lambda () PRODUCER_{1})
                (lambda FORMALS_{1}
                  ...BODY...))))

     'Mvlet' is similar, but each PRODUCER is evaluated in an
     environment where none of the variables in any of the FORMALS is
     bound, and the order in which each producer expression is evaluated
     is unspecified.

6.8.7 Object dumper
-------------------

Scheme48 has a rudimentary object dumper and retriever in the structure
'dump/restore'.  It is not a 'real' object dumper in the sense that it
will not handle cycles in object graphs correctly; it simply performs a
recursive descent and will diverge if it reaches a cycle or stop after a
recursive depth parameter.

   The types of objects that the dumper supports are: several
miscellaneous constants ('()', '#t', '#f', & the unspecific token),
pairs, vectors, symbols, numbers, strings, characters, and byte vectors.

 -- procedure: dump object char-writer depth --> unspecified
     Dumps OBJECT by repeatedly calling CHAR-WRITER, which must be a
     procedure that accepts exactly one character argument, on the
     characters of the serialized representation.  If the dumper
     descends into the object graph whose root is OBJECT for more than
     DEPTH recursions, an ellipsis token is dumped in the place of the
     vertex at DEPTH.

 -- procedure: restore char-reader --> object
     Restores the object whose serialized components are retrieved by
     repeatedly calling CHAR-READER, which must be a procedure that
     accepts zero arguments and returns a character.

6.8.8 Simple time access
------------------------

The 'time' structure exports a simple facility for accessing time
offsets in two different flavours.

 -- procedure: real-time --> milliseconds
     Returns the real time in milliseconds that has passed since some
     unspecified moment in time.(1)  Though not suitable for
     measurements relative to entities outside the Scheme48 image, the
     real time is useful for measuring time differences within the
     Scheme image with reasonable precision; for example, thread sleep
     timing is implemented with this real time primitive.

 -- procedure: run-time --> ticks
     Returns the run time as an integer representing processor clock
     ticks since the start of the Scheme48 process.  This is much less
     precise than the real time, but it is useful for measuring time
     actually spent in the Scheme48 process, as opposed to time in
     general.

   ---------- Footnotes ----------

   (1) In the current implementation on Unix, this moment happens to be
the first call to 'real-time'; on Win32, this is the start of the Scheme
process.


File: scheme48.info,  Node: C interface,  Next: POSIX interface,  Prev: Libraries,  Up: Top

7 C interface
*************

(This chapter was derived from work copyrighted (C) 1993-2005 by Richard
Kelsey, Jonathan Rees, and Mike Sperber.)

This chapter describes an interface for calling C functions from Scheme,
calling Scheme procedures from C, and working with the Scheme heap in C.
Scheme48 manages stub functions in C that negotiate between the calling
conventions of Scheme & C and the memory allocation policies of both
worlds.  No stub generator is available yet, but writing stubs is a
straightforward task.

* Menu:

* Shared bindings between Scheme and C::
* Calling C functions from Scheme::
* Dynamic loading of C modules::
* Accessing Scheme data from C::
* Calling Scheme procedures from C::
* Interacting with the Scheme heap in C::
* Using Scheme records in C::
* Raising exceptions from C::
* Unsafe C macros::

7.1 Overview of the C interface
===============================

The following facilities are available for interfacing between Scheme48
& C:

   * Scheme code can call C functions.
   * The external interface provides full introspection for all Scheme
     objects.  External code may inspect, modify, and allocate Scheme
     objects arbitrarily.
   * External code may raise exceptions back to Scheme48 to signal
     errors.
   * External code may call back into Scheme.  Scheme48 correctly
     unrolls the process stack on non-local exits.
   * External modules may register bindings of names to values with a
     central registry accessible from Scheme.  Conversely, Scheme code
     can register shared bindings for access by C code.

7.1.1 Scheme structures
-----------------------

On the Scheme side of the C interface, there are three pertinent
structures: 'shared-bindings' (*note Shared bindings between Scheme and
C::), which provides the Scheme side of the facility for sharing data
between Scheme and C; 'external-calls' (*note Calling C functions from
Scheme::), which exports several ways to call C functions from Scheme,
along with some useful facilities, such as object finalizers, which are
also available from elsewhere; and 'load-dynamic-externals' (*note
Dynamic loading of C modules::), which provides a dynamic external
object loading facility.  Also, the old dynamic loading facility is
still available from the 'dynamic-externals' structure, but its use is
deprecated, and it will most likely vanish in a later release.

7.1.2 C naming conventions
--------------------------

Scheme48's C bindings all have strict naming conventions.  Variables &
procedures have 's48_' prefixed to them; macros, 'S48_'.  Whenever a C
name is derived from a Scheme identifier, hyphens are replaced with
underscores.  Also, procedures or variables are converted to lowercase,
while macros are converted to uppercase.  The '?' suffix, generally
appended to predicates, is converted to '_p' (or '_P' in macro names).
Trailing '!' is dropped.  For example, the C macro that corresponds with
Scheme's 'pair?' predicate is named 'S48_PAIR_P', and the C macro to
assign the car of a pair is named 'S48_SET_CAR'.  Procedures and macros
that do not verify the types of their arguments have 'unsafe' in their
names.

   All of the C functions and macros described have prototypes or
definitions in the file 'c/scheme48.h' of Scheme48's standard
distribution.  The C type for Scheme values is defined there to be
's48_value'.

7.1.3 Garbage collection
------------------------

Scheme48 uses a copying garbage collector.  The collector must be able
to locate all references to objects allocated in the Scheme48 heap in
order to ensure that storage is not reclaimed prematurely and to update
references to objects moved by the collector.  The garbage collector may
run whenever an object is allocated in the heap.  C variables whose
values are Scheme48 objects and which are live across heap allocation
calls need to be registered with the garbage collector.  For more
information, *note Interacting with the Scheme heap in C::.


File: scheme48.info,  Node: Shared bindings between Scheme and C,  Next: Calling C functions from Scheme,  Up: C interface

7.2 Shared bindings between Scheme and C
========================================

Shared bindings are the means by which named values are shared between
Scheme & C code.  There are two separate tables of shared bindings, one
for values defined in Scheme and accessed from C and the other for the
opposite direction.  Shared bindings actually bind names to cells, to
allow a name to be resolved before it has been assigned.  This is
necessary because C initialization code may run before or after the
corresponding Scheme code, depending on whether the Scheme code is in
the resumed image or run in the current session.  The Scheme bindings
described here are available from the 'shared-bindings' structure.

7.2.1 Scheme shared binding interface
-------------------------------------

 -- Scheme procedure: shared-binding? object --> boolean
 -- Scheme procedure: shared-binding-is-import? shared-binding -->
          boolean
     'Shared-binding?' is the disjoint type predicate for all shared
     bindings, imported or exported; 'shared-binding-is-import?' returns
     true if SHARED-BINDING was imported into Scheme from C, and false
     if it has the converse direction.

 -- Scheme procedure: shared-binding-ref shared-binding --> value
 -- Scheme procedure: shared-binding-set! shared-binding value -->
          unspecified
     'Shared-binding-ref' returns the value of SHARED-BINDING;
     'shared-binding-set!' sets the value of SHARED-BINDING to be VALUE.

 -- Scheme procedure: lookup-imported-binding name --> shared-binding
 -- Scheme procedure: define-imported-binding name value --> unspecified
 -- Scheme procedure: undefine-imported-binding name --> unspecified
     'Lookup-imported-binding' returns the binding imported from C to
     Scheme with the given name; a binding is created if none exists.
     'Define-imported-binding' creates a new such binding, anomalously
     from within Scheme; such bindings are usually created instead from
     within C using the C 's48_define_exported_binding' function.
     'Undefine-imported-binding' removes the shared binding whose name
     is NAME from the table of imported bindings.

 -- Scheme procedure: lookup-exported-binding name --> shared-binding
 -- Scheme procedure: define-exported-binding name value --> unspecified
 -- Scheme procedure: undefine-exported-binding name --> unspecified
     Equivalents of the above three procedures, but for bindings
     exported from Scheme to C. 'Define-imported-binding', unlike
     'define-exported-binding', is customary to use in Scheme, as its
     intended use is to make a Scheme value available to C code from
     within Scheme.

 -- Scheme procedure: find-undefined-imported-bindings --> vector
     Returns a vector of all bindings imported into Scheme from C with
     undefined values, i.e. those created implicitly by lookups that
     have not yet been assigned rather than those created explicitly by
     the shared binding definers ('define-exported-binding', &c.).

7.2.2 C shared binding interface
--------------------------------

 -- C macro: s48_value S48_SHARED_BINDING_P (s48_value OBJ)
 -- C macro: s48_value S48_SHARED_BINDING_NAME (s48_value
          SHARED_BINDING)
 -- C macro: s48_value S48_SHARED_BINDING_IS_IMPORTP (s48_value
          SHARED-BINDING)
 -- C macro: s48_value S48_SHARED_BINDING_REF (s48_value SHARED_BINDING)
 -- C macro: void S48_SHARED_BINDING_SET (s48_value SHARED_BINDING,
          s48_value VALUE)
     These macros are C counterparts to Scheme's 'shared-binding?',
     'shared-binding-name', 'shared-binding-is-import?',
     'shared-binding-ref', and 'shared-binding-set!', respectively.

 -- C macro: statement S48_SHARED_BINDING_CHECK (s48_value BINDING)
     Signals an exception if and only if BINDING's value is Scheme48's
     'unspecific' value.

     *Huh?:* Undefined shared bindings are not initialized with the
     'unspecific' value, but rather with an entirely different special
     token referred to internally as 'undefined,' used in circumstances
     such as this -- yet 'S48_SHARED_BINDING_CHECK', as defined in
     'scheme48.h', definitely checks whether BINDING's value is the
     'unspecific' value.

 -- C function: s48_value s48_get_imported_binding (char *NAME)
     Returns the shared binding defined in Scheme for NAME, creating it
     if necessary.

 -- C function: void s48_define_exported_binding (char *NAME, s48_value
          VALUE)
     Defines a shared binding named NAME with the value VALUE that can
     be accessed from Scheme.

 -- C macro: void S48_EXPORT_FUNCTION (FN)
     This is a convenience for the common case of exporting a C function
     to Scheme.  This expands into

          s48_define_exported_binding("FN",
                                      s48_enter_pointer(FN))

     which boxes the function into a Scheme48 byte vector and then
     exports it as a shared binding.  Note that 's48_enter_pointer'
     allocates space in the Scheme heap and may trigger a garbage
     collection; *note Interacting with the Scheme heap in C::.


File: scheme48.info,  Node: Calling C functions from Scheme,  Next: Dynamic loading of C modules,  Prev: Shared bindings between Scheme and C,  Up: C interface

7.3 Calling C functions from Scheme
===================================

The 'external-calls' structure exports several ways to call C functions
from Scheme, along with several other related utilities, many of which
are also available from other structures.  There are two different ways
to call C functions from Scheme, depending on how the C function was
obtained:

 -- Scheme procedure: call-imported-binding binding argument ... -->
          value
 -- Scheme procedure: call-external-value byte-vector name argument ...
          --> value
     Each of these applies its first argument, a C function, to the rest
     of the arguments.  For 'call-imported-binding', the function
     argument must be an imported binding.  For 'call-external-value',
     the function argument must be a byte vector that contains a pointer
     to a C function, and NAME should be a string that names the
     function.  The NAME argument is used only for printing error
     messages.

     For both of these, the C function is passed the argument values,
     and the value returned is that returned by the C function.  No
     automatic representation conversion occurs for either arguments or
     return values.  Up to twelve arguments may be passed.  There is no
     method supplied for returning multiple values to Scheme from C or
     vice versa (mainly because C does not have multiple return values).

     Keyboard interrupts that occur during a call to a C function are
     ignored until the function returns to Scheme.(1)

 -- Scheme syntax: import-definition name [c-string]
 -- Scheme syntax: import-lambda-definition name formals [c-string]
     These macros simplify importing bindings from C into Scheme and
     wrapping such bindings in Scheme procedures.  'Import-definition'
     defines NAME to be the shared binding named by C-STRING, whose
     value, if it is not supplied, is by default a string of NAME,
     downcased and with all hyphens translated to underscores.

          (define NAME (lookup-imported-binding C-STRING))

     For example,

          (import-definition my-foo)
              ==> (define my-foo (lookup-imported-binding "my_foo"))

     'Import-lambda-definition' imports the named C binding, using
     either the provided C binding name or by translating the Scheme
     name as with 'import-definition', and defines NAME to be a
     procedure with the given formal parameter list that calls the
     imported C binding with its arguments:

          (define BINDING (lookup-imported-binding C-STRING))
          (define (NAME FORMAL ...)
            (call-imported-binding BINDING FORMAL ...))

     Examples:

          (import-lambda-definition integer->process-id (int)
                                    "posix_getpid")
              ==>
          (define BINDING_{0}
                  (lookup-imported-binding "posix_getpid"))
          (define (integer->process-id int)
            (call-imported-binding BINDING_{0} int))

          (import-lambda-definition s48-system (string))
              ==>
          (define BINDING_{1}
                  (lookup-imported-binding "s48_system"))
          (define (s48-system string)
            (call-imported-binding BINDING_{1} string))

     where BINDING_{0} and BINDING_{1} are fresh, unused variable names.

     *Warning:* 'Import-lambda-definition', as presently implemented,
     requires a fixed parameter list; it does not allow 'rest list'
     arguments.

 -- Scheme procedure: lookup-imported-binding name --> shared-binding
 -- Scheme procedure: define-exported-binding shared-binding -->
          unspecified
 -- Scheme procedure: shared-binding-ref shared-binding --> value
     These are identical to the procedures accessible with the same
     names from the 'shared-bindings' structure (*note Shared bindings
     between Scheme and C::).

 -- Scheme procedure: add-finalizer! object procedure --> unspecified
     Registers PROCEDURE as the finalizer for OBJECT.  When OBJECT is
     later about to be reclaimed by the garbage collector, PROCEDURE is
     applied to one argument, OBJECT.  All finalizers are applied in a
     child of the root scheduler thread that is spawned after every
     garbage collection.  If an error occurs in any finalizer, it will
     be printed to the standard error output port, and all other
     finalizers will be aborted before they are given a chance to run.
     Because of this, and the fact that finalizers are collected and run
     after every garbage collection, they should perform as little
     computation as possible.  PROCEDURE may also create new references
     to OBJECT elsewhere in the heap, in which case the object will not
     be reclaimed, but its associated finalizer will be forgotten.

     *Warning:* Finalizers are expensive.  Use sparingly.

 -- Scheme procedure: define-record-resumer record-type resumer -->
          unspecified
     Identical to the procedure accessible with the same name from the
     'record-types' structure (*note Records::).  Record resumers are
     often useful in working with foreign C data, which is in many cases
     specific to the program image within the operating system, and
     which cannot straightforwardly be relocated to a different address
     space.

   ---------- Footnotes ----------

   (1) This is clearly a problem; we are working on a solution.


File: scheme48.info,  Node: Dynamic loading of C modules,  Next: Accessing Scheme data from C,  Prev: Calling C functions from Scheme,  Up: C interface

7.4 Dynamic loading of C modules
================================

External code can be loaded into a running Scheme48 on most Unices and
on Windows.  Such external code must be stored in shared objects; see
below on details of the C side.  The relevant Scheme procedures are
available in the 'load-dynamic-externals' structure:

 -- procedure: load-dynamic-externals filename add-file-type?
          reload-on-repeat? reload-on-resume? --> dynamic-externals
 -- procedure: import-dynamic-externals filename --> dynamic-externals
 -- procedure: unload-dynamic-externals dynamic-externals -->
          unspecified
     'Load-dynamic-external' loads a shared object from FILENAME, with
     an appropriate file type appended if ADD-FILE-TYPE? is true ('.so'
     on Unix and '.dll' on Windows), and returns a "dynamic externals"
     object representing the loaded shared object.  If the shared object
     was already loaded, then if RELOAD-ON-REPEAT? is true, it is
     reloaded; otherwise, the 'load-dynamic-externals' call has no
     effect.  If the dynamic externals descriptor is stored in a dumped
     heap image, when that heap image is resumed, if 'reload-on-resume?'
     is true, the shared object corresponding with that dynamic external
     descriptor is reloaded.  'Unload-dynamic-externals' unloads the
     given dynamic externals object.

     'Import-dynamic-externals' is a convenient wrapper for the common
     case of 'load-dynamic-externals'; it is equivalent to
     '(load-dynamic-externals #t #f #t)', i.e. it will append a file
     type, it will not reload the shared object if it was already
     loaded, and the shared object will be loaded if part of a resumed
     heap image.

 -- procedure: reload-dynamic-externals filename --> unspecified
     Reloads the shared object named by FILENAME.  This is intended as
     an interactive utility, which is why it accepts the filename of the
     shared object and not a dynamic externals descriptor.

   Shared objects intended to be loaded into Scheme48 must define two
functions:

 -- C function: void s48_on_load (void)
 -- C function: void s48_on_reload (void)
     's48_on_load' is called when the shared object is initially loaded
     by Scheme48.  It typically consists of a number of invocations of
     'S48_EXPORT_FUNCTION' to make C functions available to Scheme48
     code.  's48_on_reload' is called when the shared object is reloaded
     after it has been initially loaded once; it typically just calls
     's48_on_load', but it may perform other reinitializations.

   On Linux, the following commands compile the C source file 'foo.c'
into a shared object 'foo.so' that can be loaded dynamically by
Scheme48:

     % gcc -c -o foo.o foo.c
     % ld -shared -o foo.so foo.o

7.4.1 Old dynamic loading interface
-----------------------------------

The old 'dynamic-externals' structures, which exported 'dynamic-load',
'get-external', 'lookup-external', 'lookup-all-externals', 'external?',
'external-name', 'external-value', and 'call-external', is still
supported, but it will not work on Windows, its use is deprecated, and
it is likely to vanish in a future release.  The old documentation is
preserved to aid updating of old code:

   On architectures that support it, external code can be loaded into a
running Scheme48 process, and C object file bindings can be accessed at
runtime & their values called.  These Scheme procedures are exported by
the structure 'dynamic-externals'.

   In some Unices, retrieving a value from the current process may
require a non-trivial amount of computation.  We recommend that a
dynamically loaded file contain a single initialization function that
creates shared bindings for the values exported by the file.

 -- Scheme procedure: dynamic-load string --> unspecified
     Loads the filename named by STRING into the current process.  An
     exception is raised if the file cannot be found or if dynamic
     loading is not supported by the host operating system.  The file
     must have been compiled & linked appropriately.  For Linux, for
     example, the following commands compile 'foo.c' into a file
     'foo.so' that can be loaded dynamically:

          % gcc -c -o foo.o foo.c
          % ld -shared -o foo.so foo.o

 -- Scheme procedure: get-external string --> external
 -- Scheme procedure: external? object --> boolean
 -- Scheme procedure: external-name external --> string
 -- Scheme procedure: external-value external --> byte-vector
     These procedures access external values bound in the current
     process.  'Get-external' returns a "external" object that contains
     the value of the C binding with the name STRING.  It signals a
     warning if there is no such binding in the current process.
     'External?' is the disjoint type predicate for externals, and
     'external-name' & 'external-value' return the name & value of an
     external.  The value is represented as a byte vector (*note Bitwise
     manipulation::) of length four on 32-bit architectures.  The value
     is that of the C binding from when 'get-external' (or
     'lookup-external', as described below) was called.

 -- Scheme procedure: lookup-external external --> boolean
 -- Scheme procedure: lookup-all-externals --> boolean
     'Lookup-external' updates the value of EXTERNAL by looking up its
     binding in the current process.  It returns '#t' if the external is
     bound and '#f' if not.  'Lookup-all-externals' calls
     'lookup-external' on all externals in the current Scheme48 image.
     It returns '#t' if all were bound and '#f' if there was at least
     one unbound external.

 -- Scheme procedure: call-external external argument ... --> value
     Calls the C function pointed to by EXTERNAL with the given
     arguments, and returns the value that the C function returned.
     This is like 'call-imported-binding' and 'call-external-value'
     except that the function argument is represented as an external,
     not as an imported binding or byte vector containing a pointer.
     For more details, *note Calling C functions from Scheme::.


File: scheme48.info,  Node: Accessing Scheme data from C,  Next: Calling Scheme procedures from C,  Prev: Dynamic loading of C modules,  Up: C interface

7.5 Accessing Scheme data from C
================================

The C header file 'scheme48.h' provides access to Scheme48 data
structures.  The type 's48_value' is used for Scheme values.  When the
type of a value is known, such as the integer returned by the Scheme
procedure 'vector-length' or the boolean returned by 'pair', the
corresponding C function returns a C value of the appropriate type, not
an 's48_value'.  Predicates return '1' for true and '0' for false.

 -- C macro: s48_value S48_FALSE
 -- C macro: s48_value S48_TRUE
 -- C macro: s48_value S48_NULL
 -- C macro: s48_value S48_UNSPECIFIC
 -- C macro: s48_value S48_EOF
 -- C macro: long S48_MAX_FIXNUM_VALUE
 -- C macro: long S48_MIN_FIXNUM_VALUE
     These C macros denote various Scheme constants.  'S48_FALSE' is the
     boolean false value, written in Scheme as '#f'.  'S48_TRUE' is the
     boolean true value, or '#t'.  'S48_NULL' is the empty list '()'.
     'S48_UNSPECIFIC' is a miscellaneous value returned by procedures
     that have no meaningful return value (accessed in Scheme48 by the
     nullary procedure 'unspecific' in the 'util' structure).  'S48_EOF'
     is the end-of-file object (which the Scheme procedure 'eof-object?'
     answers true for).  'S48_MAX_FIXNUM_VALUE' is the maximum integer
     as a 'long' that can be represented in a Scheme48 fixnum.
     'S48_MIN_FIXNUM_VALUE' is similar, but the minimum integer.

 -- C macro: int S48_EXTRACT_BOOLEAN (s48_value BOOLEAN)
 -- C function: unsigned char s48_extract_char (s48_value CHAR)
 -- C function: char * s48_extract_string (s48_value STRING)
 -- C function: char * s48_extract_byte_vector (s48_value BYTEV)
 -- C function: long s48_extract_integer (s48_value INTEGER)
 -- C function: double s48_extract_double (s48_value DOUBLE)
 -- C macro: s48_value S48_ENTER_BOOLEAN (int BOOLEAN)
 -- C function: s48_value s48_enter_char (unsigned char CHAR)
 -- C function: s48_value s48_enter_string (char *STRING)
 -- C function: s48_value s48_enter_byte_vector (char *BYTEV, long
          LENGTH)
 -- C function: s48_value s48_enter_integer (long INTEGER)
 -- C function: s48_value s48_enter_double (double DOUBLE)
     These functions & macros convert values between their respective
     Scheme & C representations.

     'S48_EXTRACT_BOOLEAN' returns '0' if BOOLEAN is '#f' and '1'
     otherwise.  'S48_ENTER_BOOLEAN' returns the Scheme value '#f' if
     its argument is zero and '#t' otherwise.

     's48_extract_char' & 's48_enter_char' convert between Scheme
     characters and C 'char's.

     's48_extract_string' & 's48_extract_byte_vector' return pointers to
     the actual storage used by STRING or BYTEV.  These pointers are
     valid only until the next garbage collection, however; *note
     Interacting with the Scheme heap in C::.  's48_enter_string' &
     's48_enter_byte_vector' allocate space on the Scheme48 heap for the
     given strings or byte vectors.  's48_enter_string' copies the data
     starting from the pointer it is given up to the first ASCII 'NUL'
     character, whereas 's48_enter_byte_vector' is given the number of
     bytes to copy into the Scheme heap.

     's48_extract_integer' returns a C 'long' that represents the Scheme
     integer as input.  If the Scheme integer is too large to be
     represented in a long, an exception is signalled.  (The Scheme
     integer may be a fixnum or a bignum.)  's48_enter_integer' converts
     back to Scheme integers, and it will never signal an exception.

     's48_extract_double' & 's48_enter_double' convert between Scheme &
     C double-precision floating point representations.

     Of these, 's48_enter_string', 's48_enter_byte_vector',
     's48_enter_integer', & 's48_enter_double' may cause the garbage
     collector to be invoked: the former two copy the string or byte
     vector onto the Scheme heap first, 's48_enter_integer' may need to
     allocate a bignum (since C 'long's are wider than Scheme48
     fixnums), and floats are heap-allocated in Scheme48.

 -- C macro: int S48_TRUE_P (s48_value OBJECT)
 -- C macro: int S48_FALSE_P (s48_value OBJECT)
     'S48_TRUE_P' returns true if OBJECT is the true constant 'S48_TRUE'
     and false if otherwise.  'S48_FALSE_P' returns true if its argument
     is the false constant 'S48_FALSE' and false if otherwise.

 -- C macro: int S48_FIXNUM_P (s48_value OBJECT)
 -- C function: long s48_extract_fixnum (s48_value FIXNUM)
 -- C function: s48_value s48_enter_fixnum (long INTEGER)
     'S48_FIXNUM_P' is the C predicate for Scheme48 fixnums, delimited
     in range by 'S48_MIN_FIXNUM_VALUE' & 'S48_MAX_FIXNUM_VALUE'.
     's48_extract_fixnum' returns the C 'long' representation of the
     Scheme fixnum, and 's48_enter_fixnum' returns the Scheme fixnum
     representation of the C 'long'.  These are identical to
     's48_extract_integer' & 's48_enter_integer', except that
     's48_extract_fixnum' will never raise a range exception, but
     's48_enter_fixnum' may, and 's48_enter_fixnum' will never return a
     bignum; this is due to the fact that C 'long's have a wider range
     than Scheme48 fixnums.

 -- C macro: int S48_EQ_P (s48_value A, s48_value B)
 -- C macro: int S48_CHAR_P (s48_value OBJECT)
 -- C macro: int S48_PAIR_P (s48_value OBJECT)
 -- C macro: int S48_VECTOR_P (s48_value OBJECT)
 -- C macro: int S48_STRING_P (s48_value OBJECT)
 -- C macro: int S48_SYMBOL_P (s48_value OBJECT)
 -- C macro: int S48_BYTE_VECTOR_P (s48_value OBJECT)
 -- C macro: s48_value S48_CAR (s48_value PAIR)
 -- C macro: s48_value S48_CDR (s48_value PAIR)
 -- C macro: void S48_SET_CAR (s48_value PAIR, s48_value OBJECT)
 -- C macro: void S48_SET_CDR (s48_value PAIR, s48_value OBJECT)
 -- C function (may GC): s48_value s48_cons (s48_value CAR, s48_value
          CDR)
 -- C function: s48_value s48_length (s48_value LIST)
 -- C macro: long S48_VECTOR_LENGTH (s48_value VECTOR)
 -- C macro: s48_value S48_VECTOR_REF (s48_value VECTOR, long INDEX)
 -- C macro: void S48_VECTOR_SET (s48_value VECTOR, long INDEX,
          s48_value OBJECT)
 -- C function (may GC): s48_value s48_make_vector (long LENGTH,
          s48_value FILL)
 -- C macro: long S48_STRING_LENGTH (s48_value STRING)
 -- C macro: char S48_STRING_REF (s48_value STRING, long INDEX)
 -- C macro: void S48_STRING_SET (s48_value STRING, long INDEX, char
          CHAR)
 -- C function (may GC): s48_value s48_make_string (long LENGTH, char
          FILL)
 -- C macro: s48_value S48_SYMBOL_TO_STRING (s48_value SYMBOL)
 -- C macro: long S48_BYTE_VECTOR_LENGTH (s48_value BYTEV)
 -- C macro: char S48_BYTE_VECTOR_REF (s48_value BYTEV, long INDEX)
 -- C macro: void S48_BYTE_VECTOR_SET (s48_value BYTEV, long INDEX, char
          BYTE)
 -- C function (may GC): s48_value s48_make_byte_vector (long LENGTH)
     C versions of miscellaneous Scheme procedures.  The names were
     derived from their Scheme counterparts by replacing hyphens with
     underscores, '?' suffixes with '_P', and dropping '!' suffixes.


File: scheme48.info,  Node: Calling Scheme procedures from C,  Next: Interacting with the Scheme heap in C,  Prev: Accessing Scheme data from C,  Up: C interface

7.6 Calling Scheme procedures from C
====================================

 -- C function: s48_value s48_call_scheme (s48_value PROC, long NARGS,
          ...)
     Calls the Scheme procedure PROC on NARGS arguments, which are
     passed as additional arguments to 's48_call_scheme'.  There may be
     at most twelve arguments.  The value returned by the Scheme
     procedure is returned to the C procedure.  Calling any Scheme
     procedure may potentially cause a garbage collection.

   There are some complications that arise when mixing calls from C to
Scheme with continuations & threads.  C supports only downward
continuations (via 'longjmp()').  Scheme continuations that capture a
portion of the C stack have to follow the same restriction.  For
example, suppose Scheme procedure 's0' captures continuation 'a' and
then calls C function 'c0', which in turn calls Scheme procedure 's1'.
'S1' can safely call the continuation 'a', because that is a downward
use.  When 'a' is called, Scheme48 will remove the portion of the C
stack used by the call to 'c0'.  On the other hand, if 's1' captures a
continuation, that continuation cannot be used from 's0', because, by
the time control returns to 's0', the C stack used by 's0' will no
longer be valid.  An attempt to invoke an upward continuation that is
closed over a portion of the C stack will raise an exception.

   In Scheme48, threads are implemented using continuations, so the
downward restriction applies to them as well.  An attempt to return from
Scheme to C at a time when the appropriate C frame is not on the top of
the C stack will cause the current thread to block until the frame is
available.  For example, suppose thread 't0' calls a C function that
calls back to Scheme, at which point control switches to thread 't1',
which also calls C & then back to Scheme.  At this point, both 't0' &
't1' have active calls to C on the C stack, with 't1''s C frame above
't0''s.  If 't0' attempts to return from Scheme to C, it will block,
because the frame is not yet accessible.  Once 't1' has returned to C
and from there back to Scheme, 't0' will be able to resume.  The return
to Scheme is required because context switches can occur only while
Scheme code is running.  'T0' will also be able to resume if 't1' uses a
continuation to throw past its call out to C.


File: scheme48.info,  Node: Interacting with the Scheme heap in C,  Next: Using Scheme records in C,  Prev: Calling Scheme procedures from C,  Up: C interface

7.7 Interacting with the Scheme heap in C
=========================================

Scheme48 uses a precise copying garbage collector.  Any code that
allocates objects within the Scheme48 heap may trigger a garbage
collection.  Variables bound to values in the Scheme48 heap need to be
registered with the garbage collector so that the value will be safely
held and so that the variables will be updated if the garbage collector
moves the object.  The garbage collector has no facility for updating
pointers to the interiors of objects, so such pointers, for example the
ones returned by 'S48_EXTRACT_STRING', will likely become invalid when a
garbage collection occurs.

 -- C macro: S48_DECLARE_GC_PROTECT (N)
 -- C macro: void S48_GC_PROTECT_N (s48_value VAR_{1}, ..., s48_value
          VAR_{N})
 -- C macro: void S48_GC_UNPROTECT ()
     'S48_DECLARE_GC_PROTECT', where 1 <= N <= 9, allocates storage for
     registering N variables.  At most one use of
     'S48_DECLARE_GC_PROTECT' may occur in a block.  After declaring a
     GC protection, 'S48_GC_PROTECT_N' registers the N variables with
     the garbage collector.  It must be within the scope that the
     'S48_DECLARE_GC_PROTECT' occurred in and before any code that can
     cause a garbage collection.  'S48_GC_UNPROTECT' removes the current
     block's protected variables from the garbage collector's list.  It
     must be called at the end of the block after any code that may
     cause a garbage collection.  Omitting any of the three may cause
     serious and hard-to-debug problems, because the garbage collector
     may relocate an object and invalidate unprotected 's48_value'
     pointers.  If not 'S48_DECLARE_GC_PROTECT' is matched with a
     'S48_GC_UNPROTECT' or vice versa, a 'gc-protection-mismatch'
     exception is raised when a C procedure returns to Scheme.

 -- C macro: void * S48_GC_PROTECT_GLOBAL (GLOBAL)
 -- C macro: void S48_GC_UNPROTECT_GLOBAL (void *HANDLE)
     'S48_GC_PROTECT_GLOBAL' permanently registers the l-value GLOBAL
     with the system as a garbage collection root.  It returns a pointer
     which may then be supplied to 'S48_GC_UNPROTECT_GLOBAL' to
     unregister the l-value as a root.

7.7.1 Keeping C data structures in the Scheme heap
--------------------------------------------------

C data structures can be stored within the Scheme heap by embedding them
inside byte vectors (*note Bitwise manipulation::).  The following
macros can be used to create and access embedded C objects.

 -- C macro: s48_value S48_MAKE_VALUE (TYPE)
 -- C macro: TYPE S48_EXTRACT_VALUE (s48_value BYTEV, TYPE)
 -- C macro: TYPE * S48_EXTRACT_VALUE_POINTER (s48_value BYTEV, TYPE)
 -- C macro: void S48_SET_VALUE (s48_value BYTEV, TYPE, TYPE VALUE)
     'S48_MAKE_VALUE' allocates a byte vector large enough to hold a C
     value whose type is TYPE.  'S48_EXTRACT_VALUE' returns the contents
     of the byte vector BYTEV cast to TYPE, and
     'S48_EXTRACT_VALUE_POINTER' returns a pointer to the contents of
     the byte vector, which is valid only until the next garbage
     collection.  'S48_SET_VALUE' stores a value into the byte vector.

7.7.2 C code and heap images
----------------------------

Scheme48 uses dumped heap images to restore a previous system state.
The Scheme48 heap is written into a file in a machine-independent and
operating-system-independent format.  The procedures described above,
however, may be used to create objects in the Scheme heap that contain
information specific to the current machine, operating system, or
process.  A heap image containing such objects may not work correctly
when resumed.

   To address this problem, a record type may be given a "resumer"
procedure.  On startup, the resumer procedure for a record type is
applied to each record of that type in the image being restarted.  This
procedure can update the record in a manner appropriate to the machine,
operating system, or process used to resume the image.  Note, though,
that there is no reliable order in which record resumer procedures are
applied.  To specify the resumer for a record type, use the
'define-record-resumer' procedure from the 'record-types' structure
(*note Records::).


File: scheme48.info,  Node: Using Scheme records in C,  Next: Raising exceptions from C,  Prev: Interacting with the Scheme heap in C,  Up: C interface

7.8 Using Scheme records in C
=============================

External C code can create records and access record slots positionally
using these functions & macros.  Note, however, that named access to
record fields is not supported, only indexed access, so C code must be
synchronized carefully with the corresponding Scheme that defines record
types.

 -- C function (may GC): s48_value s48_make_record (s48_value
          RECORD-TYPE)
 -- C macro: int S48_RECORD_P (s48_value OBJECT)
 -- C macro: s48_value S48_RECORD_TYPE (s48_value RECORD)
 -- C macro: s48_value S48_RECORD_REF (s48_value RECORD, long INDEX)
 -- C macro: void S48_RECORD_SET (s48_value RECORD, long INDEX,
          s48_value VALUE)
 -- C function: void s48_check_record_type (s48_value RECORD, s48_value
          TYPE-BINDING)
     's48_make_record' allocates a record on Scheme's heap with the
     given record type; its arguments must be a shared binding whose
     value is a record type descriptor (*note Records::).
     'S48_RECORD_P' is the type predicate for records.
     'S48_RECORD_TYPE' returns the record type descriptor of RECORD.
     'S48_RECORD_REF' & 'S48_RECORD_SET' operate on records similarly to
     how 'S48_VECTOR_REF' & 'S48_VECTOR_SET' work on vectors.
     's48_check_record_type' checks whether RECORD is a record whose
     type is the value of the shared binding TYPE_BINDING.  If this is
     not the case, it signals an exception.  (It also signals an
     exception if TYPE_BINDING's value is not a record.)  Otherwise, it
     returns normally.

   For example, with this record type definition:

     (define-record-type thing :thing
       (make-thing a b)
       thing?
       (a thing-a)
       (b thing-b))

the identifier ':thing' is bound to the record type and can be exported
to C thus:

     (define-exported-binding "thing-record-type" :thing)

and 'thing' records can be made in C:

     static s48_value thing_record_type = S48_FALSE;
     void initialize_things(void)
     {
       S48_GC_PROTECT_GLOBAL(thing_record_type);
       thing_record_type = s48_get_imported_binding("thing-record-type");
     }

     s48_value make_thing(s48_value a, s48_value b)
     {
       s48_value thing;

       S48_DECLARE_GC_PROTECT(2);
       S48_GC_PROTECT_2(a, b);

       thing = s48_make_record(thing_record_type);
       S48_RECORD_SET(thing, 0, a);
       S48_RECORD_SET(thing, 1, b);

       S48_GC_UNPROTECT();

       return thing;
     }

Note that the variables 'a' & 'b' must be protected against the
possibility of a garbage collection occurring during the call to
's48_make_record'.


File: scheme48.info,  Node: Raising exceptions from C,  Next: Unsafe C macros,  Prev: Using Scheme records in C,  Up: C interface

7.9 Raising exceptions from C
=============================

The following macros raise certain errors, immediately returning to
Scheme48.  Raising an exception performs all necessary clean-up actions
to properly return to Scheme48, including adjusting the stack of
protected variables.

 -- C function: s48_raise_scheme_exception (int TYPE, int NARGS, ...)
     The base procedure for raising exceptions.  TYPE is the type of
     exception; it should be one of the 'S48_EXCEPTION_...' constants
     defined in 'scheme48.h'.  NARGS is the number of additional values
     to be included in the exception; these follow the NARGS argument
     and should all have the type 's48_value'.  NARGS may not be greater
     than ten.  's48_raise_scheme_exception' never returns.

 -- C function: s48_raise_argument_type_error (s48_value ARG)
 -- C function: s48_raise_argument_number_error (s48_value NARGS,
          s48_value MIN, s48_value MAX)
 -- C function: s48_raise_range_error (s48_value VALUE, s48_value MIN,
          s48_value MAX)
 -- C function: s48_raise_closed_channel_error ()
 -- C function: s48_raise_os_error (int ERRNO)
 -- C function: s48_raise_out_of_memory_error ()
     Conveniences for raising certain kinds of exceptions.  Argument
     type errors are due to procedures receiving arguments of the
     incorrect type.  Argument number errors are due to the number of
     arguments being passed to a procedure, NARGS, not being between MIN
     or MAX, inclusive.  Range errors are similar, but they are intended
     for larger ranges, not argument numbers.  Closed channel errors
     occur when a channel (*note Channels::) was operated upon with the
     expectation that it would not be closed.  OS errors originate from
     the OS, and they are denoted with Unix 'errno' values.

 -- C macro: void S48_CHECK_BOOLEAN (s48_value OBJECT)
 -- C macro: void S48_CHECK_SYMBOL (s48_value OBJECT)
 -- C macro: void S48_CHECK_PAIR (s48_value OBJECT)
 -- C macro: void S48_CHECK_STRING (s48_value OBJECT)
 -- C macro: void S48_CHECK_INTEGER (s48_value OBJECT)
 -- C macro: void S48_CHECK_CHANNEL (s48_value OBJECT)
 -- C macro: void S48_CHECK_BYTE_VECTOR (s48_value OBJECT)
 -- C macro: void S48_CHECK_RECORD (s48_value OBJECT)
 -- C macro: void S48_CHECK_SHARED_BINDING (s48_value OBJECT)
     Conveniences for checking argument types.  These signal argument
     type errors with 's48_raise_argument_type_error' if their argument
     is not of the type being tested.


File: scheme48.info,  Node: Unsafe C macros,  Prev: Raising exceptions from C,  Up: C interface

7.10 Unsafe C macros
====================

All of the C functions & macros described previously verify that their
arguments have the appropriate types and lie in the appropriate ranges.
The following macros are identical to their safe counterparts, except
that the unsafe variants, by contrast, do _not_ verify coherency of
their arguments.  They are provided for the purpose of writing more
efficient code; their general use is not recommended.

 -- C macro: char S48_UNSAFE_EXTRACT_CHAR (s48_value CHAR)
 -- C macro: char * S48_UNSAFE_EXTRACT_STRING (s48_value STRING)
 -- C macro: long S48_UNSAFE_EXTRACT_INTEGER (s48_value INTEGER)
 -- C macro: double S48_UNSAFE_EXTRACT_DOUBLE (s48_value DOUBLE)
 -- C macro: long S48_UNSAFE_EXTRACT_FIXNUM (s48_value FIXNUM)
 -- C macro: s48_value S48_UNSAFE_ENTER_FIXNUM (long INTEGER)

 -- C macro: s48_value S48_UNSAFE_CAR (s48_value PAIR)
 -- C macro: s48_value S48_UNSAFE_CDR (s48_value PAIR)
 -- C macro: void S48_UNSAFE_SET_CAR (s48_value PAIR, s48_value VALUE)
 -- C macro: void S48_UNSAFE_SET_CDR (s48_value PAIR, s48_value VALUE)

 -- C macro: long S48_UNSAFE_VECTOR_LENGTH (s48_value VECTOR)
 -- C macro: s48_value S48_UNSAFE_VECTOR_REF (s48_value VECTOR, long
          INDEX)
 -- C macro: void S48_UNSAFE_VECTOR_SET (s48_value VECTOR, long INDEX,
          s48_value VALUE)

 -- C macro: long S48_UNSAFE_STRING_LENGTH (s48_value STRING)
 -- C macro: char S48_UNSAFE_STRING_REF (s48_value STRING, long INDEX)
 -- C macro: void S48_UNSAFE_STRING_SET (s48_value STRING, long INDEX,
          char CHAR)

 -- C macro: void S48_UNSAFE_SYMBOL_TO_STRING (s48_value SYMBOL)

 -- C macro: long S48_UNSAFE_BYTE_VECTOR_LENGTH (s48_value BYTEV)
 -- C macro: char S48_UNSAFE_BYTE_VECTOR_REF (s48_value BYTEV, long
          INDEX)
 -- C macro: void S48_UNSAFE_BYTE_VECTOR_SET (s48_value BYTEV, long
          INDEX, char BYTE)

 -- C macro: s48_value S48_UNSAFE_SHARED_BINDING_REF (s48_value
          SHARED_BINDING)
 -- C macro: int S48_UNSAFE_SHARED_BINDING_IS_IMPORTP (s48_value
          SHARED_BINDING)
 -- C macro: s48_value S48_UNSAFE_SHARED_BINDING_NAME (s48_value
          SHARED_BINDING)
 -- C macro: void S48_UNSAFE_SHARED_BINDING_SET (s48_value
          SHARED_BINDING, s48_value VALUE)

 -- C macro: TYPE S48_UNSAFE_EXTRACT_VALUE (s48_value BYTEV, TYPE)
 -- C macro: TYPE * S48_UNSAFE_EXTRACT_VALUE_POINTER (s48_value BYTEV,
          TYPE)
 -- C macro: void S48_UNSAFE_SET_VALUE (s48_value BYTEV, TYPE, TYPE
          VALUE)


File: scheme48.info,  Node: POSIX interface,  Next: Pre-Scheme,  Prev: C interface,  Up: Top

8 POSIX interface
*****************

(This chapter was derived from work copyrighted (C) 1993-2005 by Richard
Kelsey, Jonathan Rees, and Mike Sperber.)

This chapter describes Scheme48's interface to POSIX C calls.  Scheme
versions of most of the C functions in POSIX are provided.  Both the
interface and implementation are new and likely to change significantly
in future releases.  The implementation may also contain many bugs.

   The POSIX bindings are available in several structures:

'posix-processes'
     'fork', 'exec', and other process manipulation procedures

'posix-process-data'
     procedures for accessing information about processes

'posix-files'
     POSIX file system access procedures

'posix-i/o'
     pipes and various POSIX I/O controls

'posix-time'
     POSIX time operations

'posix-users'
     user and group manipulation procedures

'posix-regexps'
     POSIX regular expression construction and matching

'posix'
     all of the above

   Scheme48's POSIX interface differs from scsh [Shivers 94; Shivers 96;
Shivers et al.  04] in several ways.  The interface here lacks scsh's
high-level constructs and utilities such as the process notation, 'awk'
facility, and parsing utilities.  Scheme48 uses disjoint types for some
values that scsh leaves as symbols or simple integers; these include
file types, file modes, and user & group ids.  Many of the names and
other interface details are different as well.

* Menu:

* POSIX processes::
* POSIX signals::
* POSIX process environment::
* POSIX users and groups::
* POSIX host OS and machine identification::
* POSIX file system access::
* POSIX time::
* POSIX I/O utilities::
* POSIX regular expressions::
* POSIX C to Scheme correspondence::


File: scheme48.info,  Node: POSIX processes,  Next: POSIX signals,  Up: POSIX interface

8.1 Processes
=============

The procedures described in this section control the creation of
subprocesses and the execution of programs.  They exported by both the
'posix-processes' and 'posix' structures.

 -- procedure: fork --> process id or '#f'
 -- procedure: fork-and-forget thunk --> unspecified
     'Fork' creates a new child process.  In the parent process, it
     returns the child's process id; in the child process, it returns
     '#f'.  'Fork-and-forget' calls THUNK in a new process; no process
     id is returned.  'Fork-and-forget' uses an intermediate process to
     avoid creating a zombie.

 -- procedure: process-id? object --> boolean
 -- procedure: process-id=? pid--_{a} pid--_{b} --> boolean
 -- procedure: process-id->integer pid --> integer
 -- procedure: integer->process-id integer --> pid
     'Process-id?' is the disjoint type predicate for process ids.
     'Process-id=?' tests whether two process ids are the same.
     'Process-id->integer' & 'integer->process-id' convert between
     Scheme48's opaque process id type and POSIX process id integers.

 -- procedure: process-id-exit-status pid --> integer or '#f'
 -- procedure: process-id-terminating-signal pid --> signal or '#f'
 -- procedure: wait-for-child-process pid --> unspecified
     If the process identified by PID exited normally or is running,
     'process-id-exit-status' and 'process-id-terminating-signal' will
     both return '#f'.  If, however, it terminated abnormally,
     'process-id-exit-status' returns its exit status, and if it exited
     due to a signal then 'process-id-terminating-signal' returns the
     signal due to which it exited.  'Wait-for-child-process' blocks the
     current process until the process identified by PID has terminated.
     Scheme48 may reap child processes before the user requests their
     exit status, but it does not always do so.

 -- procedure: exit status --> does not return
     Terminates the current process with the integer STATUS as its exit
     status.

 -- procedure: exec program argument ... --> does not return
 -- procedure: exec-with-environment program env argument ... --> does
          not return
 -- procedure: exec-file filename argument ... --> does not return
 -- procedure: exec-file-with-environment filename env argument ... -->
          does not return
     These all replace the current program with a new one.  They differ
     in how the program is found and what process environment the
     program should receive.  'Exec' & 'exec-with-environment' look up
     the program in the search path (the 'PATH' environment variable),
     while 'exec-file' & 'exec-file-with-environment' execute a
     particular file.  The environment is either inherited from the
     current process, in the cases of 'exec' & 'exec-file', or
     explicitly specified, in the cases of 'exec-with-environment' &
     'exec-file-with-environment'.  PROGRAM, FILENAME, & all ARGUMENTs
     should be strings.  ENV should be a list of strings of the form
     '"NAME=VALUE"'.  When the new program is invoked, its arguments
     consist of the program name prepended to the remaining specified
     arguments.

 -- procedure: exec-with-alias name lookup? maybe-env arguments --> does
          not return
     General omnibus procedure that subsumes the other 'exec' variants.
     NAME is looked up in the search path if LOOKUP? is true or used as
     an ordinary filename if it is false.  MAYBE-ENV is either '#f', in
     which case the new program's environment should be inherited from
     the current process, or a list of strings of the above form for
     environments, which specifies the new program's environment.
     ARGUMENTS is a list of _all_ of the program's arguments;
     'exec-with-alias' does _not_ prepend NAME to that list (hence
     '-with-alias').


File: scheme48.info,  Node: POSIX signals,  Next: POSIX process environment,  Prev: POSIX processes,  Up: POSIX interface

8.2 Signals
===========

There are two varieties of signals available, named & anonymous.  A
"named" signal is one for which there is provided a symbolic name, such
as 'kill' or 'pipe'.  Anonymous signals are those that the operating
system provided but for which POSIX does not define a symbolic name,
only a number, and which may not have meaning on other operating
systems.  Named signals preserve their meaning through heap image dumps;
anonymous signals may not be dumped in heap images.  (If they are, a
warning is signalled, and they are replaced with a special token that
denotes a non-portable signal.)  Not all named signals are available
from all operating systems, and there may be multiple names for a single
operating system signal number.

 -- syntax: signal name --> signal
 -- procedure: name->signal symbol --> signal or '#f'
 -- procedure: integer->signal integer --> signal
 -- procedure: signal? object --> boolean
 -- procedure: signal-name signal --> symbol or '#f'
 -- procedure: signal-os-number signal --> integer
 -- procedure: signal=? signal--_{a} signal--_{b} --> boolean
     'Signal' evaluates to the signal object with the known symbolic
     name NAME.  It is an error if NAME is not recognized as any
     signal's name.  'Name->signal' returns the signal corresponding
     with the given NAME or '#f' if no such signal is known.
     'Integer->signal' returns a signal, named or anonymous, with the
     given OS number.  'Signal?' is the disjoint type predicate for
     signal objects.  'Signal-name' returns the symbolic name of SIGNAL
     if it is a named signal or '#f' if it is an anonymous signal.
     'Signal-OS-number' returns the operating system's integer value of
     SIGNAL.  'Signal=?' tests whether two signals are the same, i.e.
     whether their OS numbers are equal equal.

     These are all of the symbols that POSIX defines.

     'abrt'
          abnormal termination (as by 'abort(3)')
     'alrm'
          timeout signal (as by 'alarm(2)')
     'fpe'
          floating point exception
     'hup'
          hangup on controlling terminal or death of controlling process
     'ill'
          illegal instruction
     'int'
          interrupt -- interaction attention
     'kill'
          termination signal, cannot be caught or ignored
     'pipe'
          write was attempted on a pipe with no readers
     'quit'
          interaction termination
     'segv'
          segmentation violation -- invalid memory reference
     'term'
          termination signal
     'usr1'
     'usr2'
          for use by applications
     'chld'
          child process stopped or terminated
     'cont'
          continue if stopped
     'stop'
          stop immediately, cannot be caught or ignored
     'tstp'
          interactive stop
     'ttin'
          read from control terminal attempted by a background process
     'ttou'
          write to control terminal attempted by a background process
     'bus'
          bus error -- access to undefined portion of memory

     There are also several other signals whose names are allowed to be
     passed to 'signal' that are not defined by POSIX, but that are
     recognized by many operating systems.

     'trap'
          trace or breakpoint trap
     'iot'
          synonym for 'abrt'
     'emt'
     'sys'
          bad argument to routine (SVID)
     'stkflt'
          stack fault on coprocessor
     'urg'
          urgent condition on socket (4.2 BSD)
     'io'
          I/O now possible (4.2 BSD)
     'poll'
          synonym for 'io' (System V)
     'cld'
          synonym for 'chld'
     'xcpu'
          CPU time limit exceeded (4.2 BSD)
     'xfsz'
          file size limit exceeded (4.2 BSD)
     'vtalrm'
          virtual alarm clock (4.2 BSD)
     'prof'
          profile alarm clock
     'pwr'
          power failure (System V)
     'info'
          synonym for 'pwr'
     'lock'
          file lock lost
     'winch'
          Window resize signal (4.3 BSD, Sun)
     'unused'

8.2.1 Sending & receiving signals
---------------------------------

 -- procedure: signal-process pid signal --> unspecified
     Sends a signal represented by SIGNAL to the process identified by
     PID.

   Signals received by the Scheme process can be obtained via one or
more "signal queues".  Each signal queue has a list of monitored signals
and a queue of received signals that have yet to be consumed from the
queue.  When the Scheme process receives a signal, that signal is added
to the signal queues that are currently monitoring the signal received.

 -- procedure: make-signal-queue signal-list --> signal-queue
 -- procedure: signal-queue? object --> boolean
 -- procedure: signal-queue-monitored-signals signal-queue -->
          signal-list
 -- procedure: dequeue-signal! signal-queue --> signal (may block)
 -- procedure: maybe-dequeue-signal! signal-queue --> signal or '#f'
     'Make-signal-queue' returns a new signal queue that will monitor
     all of the signals in the given list.  'Signal-queue?' is the
     disjoint type predicate for signal queues.
     'Signal-queue-monitored-signals' returns a freshly-allocated list
     of the signals currently monitored by SIGNAL-QUEUE.
     'Dequeue-signal!' & 'maybe-dequeue-signal!' both access the next
     signal ready to be read from SIGNAL-QUEUE.  If the signal queue is
     empty, 'dequeue-signal!' will block until a signal is received,
     while 'maybe-dequeue-signal!' will immediately return '#f'.

   *Note:* There is a bug in the current system that causes an erroneous
deadlock to occur if threads are blocked waiting for signals and no
other threads are available to run.  A workaround is to create a thread
that sleeps for a long time, which prevents any deadlock errors
(including real ones):

     > ,open threads
     > (spawn (lambda ()
                ;; Sleep for a year.
                (sleep (* 1000 60 60 24 365))))

 -- procedure: add-signal-queue-signal! signal-queue signal -->
          unspecified
 -- procedure: remove-signal-queue-signal! signal-queue signal -->
          unspecified
     These add & remove signals from signal queues' list of signals to
     monitor.  Note that 'remove-signal-queue-signal!' also removes any
     pending signals from the queue, so 'dequeue-signal!' &
     'maybe-dequeue-signal!' will only ever return signals that are on
     the queue's list of monitored signals when they are called.


File: scheme48.info,  Node: POSIX process environment,  Next: POSIX users and groups,  Prev: POSIX signals,  Up: POSIX interface

8.3 Process environment
=======================

These procedures are exported by the structures 'posix' &
'posix-process-data'.

 -- procedure: get-process-id --> process-id
 -- procedure: get-parent-process-id --> process-id
     These return the process id (*note POSIX processes::) of the
     current process or the current process's parent, respectively.

 -- procedure: get-user-id --> user-id
 -- procedure: get-effective-user-id --> user-id
 -- procedure: set-user-id! user-id --> unspecified
 -- procedure: get-group-id --> group-id
 -- procedure: get-effective-group-id --> group-id
 -- procedure: set-group-id! group-id --> unspecified
     These access the original and effective user & group ids (*note
     POSIX users and groups::) of the current process.  The effective
     ids may be set, but not the original ones.

 -- procedure: get-groups --> group-id list
 -- procedure: get-login-name --> string
     'Get-groups' returns a list of the supplementary groups of the
     current process.  'Get-login-name' returns a user name for the
     current process.

 -- procedure: lookup-environment-variable string --> string or '#f'
 -- procedure: environment-alist --> alist
     'Lookup-environment-variable' looks up its argument in the
     environment list of the current process and returns the
     corresponding string, or '#f' if there is none.
     'Environment-alist' returns the entire environment as a list of
     '(NAME-STRING . VALUE-STRING)' pairs.


File: scheme48.info,  Node: POSIX users and groups,  Next: POSIX host OS and machine identification,  Prev: POSIX process environment,  Up: POSIX interface

8.4 Users and groups
====================

"User ids" & "group ids" are boxed integers that represent Unix users &
groups.  Also, every user & group has a corresponding "user info" or
"group info" record, which contains miscellaneous information about the
user or group.  The procedures in this section are exported by the
structures 'posix-users' & 'posix'.

 -- procedure: user-id? object --> boolean
 -- procedure: user-id=? uid--_{a} uid--_{b} --> boolean
 -- procedure: user-id->integer uid --> integer
 -- procedure: integer->user-id integer --> uid
 -- procedure: group-id? object --> boolean
 -- procedure: group-id=? gid--_{a} gid--_{b} --> boolean
 -- procedure: group-id->integer gid --> integer
 -- procedure: integer->group-id integer --> gid
     'User-id?' & 'group-id?' are the disjoint type predicates for user
     & group ids.  'User-id=?' & 'group-id=?' test whether two user or
     group ids, respectively, are the same, i.e. whether their numbers
     are equal.  'User-id->integer', 'group-id->integer',
     'integer->user-id', & 'integer->group-id' convert between user or
     group ids and integers.

 -- procedure: user-id->user-info uid --> user-info
 -- procedure: name->user-info string --> user-info
 -- procedure: group-id->group-info gid --> group-info
 -- procedure: name->group-info string --> group-info
     These provide access for the user or group info records that
     correspond with the given user or group ids or names.

 -- procedure: user-info? object --> boolean
 -- procedure: user-info-name user-info --> string
 -- procedure: user-info-id user-info --> user-id
 -- procedure: user-info-group user-info --> group-id
 -- procedure: user-info-home-directory user-info --> string
 -- procedure: user-info-shell user-info --> string
 -- procedure: group-info? object --> boolean
 -- procedure: group-info-name group-info --> string
 -- procedure: group-info-id group-info --> group-id
 -- procedure: group-info-members group-info --> user-id-list
     'User-info?' & 'group-info?' are the disjoint type predicates for
     user info & group info records.  The others are accessors for the
     various data available in those records.


File: scheme48.info,  Node: POSIX host OS and machine identification,  Next: POSIX file system access,  Prev: POSIX users and groups,  Up: POSIX interface

8.5 Host OS and machine identification
======================================

 -- procedure: host-name --> string
 -- procedure: os-node-name --> string
 -- procedure: os-release-name --> string
 -- procedure: os-version-name --> string
 -- procedure: machine-name --> string
     These procedures return strings that are intended to identify
     various aspects of the current operating system and physical
     machine.  POSIX does not specify the format of the strings.  These
     procedures are provided by both the structure
     'posix-platform-names' and the structure 'posix'.


File: scheme48.info,  Node: POSIX file system access,  Next: POSIX time,  Prev: POSIX host OS and machine identification,  Up: POSIX interface

8.6 File system access
======================

These procedures operate on the file system via the facilities defined
by POSIX and offer more than standard & portable R5RS operations.  All
of these names are exported by the structures 'posix-files' and 'posix'.

 -- procedure: open-directory-stream filename --> dir-stream
 -- procedure: directory-stream? object --> boolean
 -- procedure: read-directory-stream dir-stream --> filename or '#f'
 -- procedure: close-directory-stream dir-stream --> unspecified
     Directory streams are the low-level interface provided by POSIX to
     enumerate the contents of a directory.  'Open-directory-stream'
     opens a new directory stream that will enumerate all of the files
     within the directory named by FILENAME.  'Directory-stream?' is the
     disjoint type predicate for directory streams.
     'Read-directory-stream' consumes the next filename from DIR-STREAM
     and returns it, or returns '#f' if the stream has finished.  Note
     that 'read-directory-stream' will return only simple filenames, not
     full pathnames.  'Close-directory-stream' closes DIR-STREAM,
     removing any storage it required in the operating system.  Closing
     an already closed directory stream has no effect.

 -- procedure: list-directory filename --> string list
     Returns the list of filenames in the directory named by FILENAME.
     This is equivalent to opening a directory stream, repeatedly
     reading from it & accumulating the list of filenames, and closing
     the stream.

 -- procedure: working-directory --> string
 -- procedure: set-working-directory! string --> unspecified
     These access the working directory's filename of the current
     process.

 -- procedure: open-file pathname file-options [file-mode] --> port
     Opens a port to the file named by the string PATHNAME.
     FILE-OPTIONS specifies various aspects of the port.  The optional
     FILE-MODE argument is used only if the file to be opened does not
     already exist; it specifies the permissions to be assigned to the
     file if it is created.  The returned port is an input port if the
     given options include 'read-only'; otherwise 'open-file' returns an
     output port.  Because Scheme48 does not support combined
     input/output ports, 'dup-switching-mode' can be used to open an
     input port for output ports opened with the 'read-write' option.

   File options are stored in a boxed mask representation.  File option
sets are created with 'file-options' and tested with 'file-options-on?'.

 -- syntax: file-options name ... --> file-options
 -- procedure: file-options-on? options--_{a} options--_{b} --> boolean
     'File-options' evaluates to a file option set, suitable for passing
     to 'open-file', that includes all of the given named options.
     'File-options-on?' returns true if OPTIONS-_{A} includes all of the
     options in OPTIONS-_{B}, or false if otherwise.

     The following file option names are supported as arguments to the
     'file-options' syntax:

     'create'
          create file if it does not already exist; a FILE-MODE argument
          is required to be passed to 'open-file' if the 'create' option
          is specified

     'exclusive'
          an error will be signalled if this option & 'create' are both
          set and the file already exists

     'no-controlling-tty'
          if the pathname being opened is a terminal device, the
          terminal will not become the controlling terminal of the
          process

     'truncate'
          file is truncated

     'append'
          written data to the newly opened file will be appended to the
          existing contents

     'nonblocking'
          read & write operations will not block

     'read-only'
          file may not be written to, only read from

     'read-write'
          file may be both read from & written to

     'write-only'
          file may not be read from, only written to

     The last three are all mutually exclusive.

   Examples:

     (open-file "some-file.txt"
                (file-options create write-only)
                (file-mode read owner-write))

returns an output port that writes to a newly-created file that can be
read from by anyone but written to only by the owner.  Once the file
'some-file.txt' exists,

     (open-file "some-file.txt"
                (file-options append write-only))

will open an output port that appends to the file.

   'I/o-flags' & 'set-i/o-flags!' (*note POSIX I/O utilities::) can be
used to access the 'append', 'nonblocking', and read/write file options
of ports, as well as modify the 'append' & 'nonblocking' options.

   To keep port operations from blocking in the Scheme48 process, output
ports are set to be nonblocking at the time of creation.  (Input ports
are managed using 'select(2)'.)  'Set-i/o-flags!' can be used to make an
output port blocking, for example directly before forking, but care
should be exercised, because the Scheme48 run-time system may be
confused if an I/O operation blocks.

 -- procedure: set-file-creation-mask! file-mode --> file-mode
     Sets the file creation mask to be FILE-MODE.  Bits set in FILE-MODE
     are cleared in the modes of any files or directories subsequently
     created by the current process.

 -- procedure: link existing-pathname new-pathname --> unspecified
 -- procedure: make-directory pathname file-mode --> unspecified
 -- procedure: make-fifo pathname file-mode --> unspecified
     'Link' creates a hard link for the file at EXISTING-PATHNAME at
     NEW-PATHNAME.  'Make-directory' creates a new directory at the
     locations specified by PATHNAME with the the file mode FILE-MODE.
     'Make-fifo' does similarly, but it creates a FIFO (first-in
     first-out) file instead of a directory.

 -- procedure: unlink pathname --> unspecified
 -- procedure: remove-directory pathname --> unspecified
 -- procedure: rename old-pathname new-pathname --> unspecified
     'Unlink' removes a link at the location PATHNAME.
     'Remove-directory' removes a directory at the location specified by
     PATHNAME.  The directory must be empty; an exception is signalled
     if it is not.  'Rename' moves the file at the location OLD-PATHNAME
     to the new location NEW-PATHNAME.

 -- procedure: accessible? pathname access-mode more-modes ... -->
          boolean
 -- syntax: access-mode name --> access mode
     'Accessible?' returns true if PATHNAME is accessible by all of the
     given access modes.  (There must be at least one access mode
     argument.)  'Access-mode' evaluates to an access mode, suitable for
     passing to 'accessible?', from the given name.  The allowed names
     are 'read', 'write', 'execute', & 'exists'.

   Information about files can be queried using the "file info"
abstraction.  Every file has a corresponding file info record, which
contains various data about the file including its name, its type, its
device & inode numbers, the number of links to it, its size in bytes,
its owner, its group, its file mode, and its access times.

 -- procedure: get-file-info pathname --> file-info
 -- procedure: get-file/link-info pathname --> file-info
 -- procedure: get-port-info fd-port --> file-info
     'Get-file-info' & 'get-file/link-info' return a file info record
     for the files named by PATHNAME.  'Get-file-info' follows symbolic
     links, however, while 'get-file/link' info does not.
     'Get-port-info' returns a file info record for the file that
     FD-PORT is a port atop a file descriptor for.  If FD-PORT does not
     read from or write to a file descriptor, an error is signalled.

 -- procedure: file-info? object --> boolean
 -- procedure: file-info-name file-info --> string
 -- procedure: file-info-device file-info --> integer
 -- procedure: file-info-inode file-info --> integer
 -- procedure: file-info-link-count file-info --> integer
 -- procedure: file-info-size file-info --> integer
 -- procedure: file-info-owner file-info --> user-id
 -- procedure: file-info-group file-info --> group-id
 -- procedure: file-info-mode file-info --> file-mode
 -- procedure: file-info-last-access file-info --> time
 -- procedure: file-info-last-modification file-info --> time
 -- procedure: file-info-last-change file-info --> time
     Accessors for various file info record fields.  The name is the
     string passed to 'get-file-info' or 'get-file/link-info', if the
     file info record was created with either of those two, or the name
     of the file that the file descriptor of the port queried was
     created on, if the file info record was obtained with
     'get-port-info'.

 -- procedure: file-info-type file-info --> file-type
 -- syntax: file-type name --> file-type
 -- procedure: file-type? object --> boolean
 -- procedure: file-type-name file-type --> symbol
     'File-info-type' returns the type of the file as a "file type"
     object.  File types may be compared using 'eq?'.  'File-type'
     evaluates to a file type of the given name.  The disjoint type
     predicate for file types is 'file-type?'.  'File-type-name' returns
     the symbolic name that represents FILE-TYPE.

     The valid file type names are:

          'regular'
          'directory'
          'character-device'
          'block-device'
          'fifo'
          'symbolic-link' (not required by POSIX)
          'socket' (not required by POSIX)
          'other'

   "File modes" are boxed integers that represent POSIX file protection
masks.

 -- syntax: file-mode permission-name ... --> file-mode
 -- procedure: file-mode? object --> boolean
     'File-mode' evaluates to a file mode object that contains all of
     the specified permissions.  'File-mode?' is the disjoint type
     predicate for file mode descriptor objects.  These are all of the
     names, with their corresponding octal bit masks and meanings,
     allowed to be passed to 'file-mode':

     Permission name   Octal mask   Description
     'set-uid'         '#o4000'     set user id when executing
     'set-gid'         '#o2000'     set group id when executing
     'owner-read'      '#o0400'     read by owner
     'owner-write'     '#o0200'     write by owner
     'owner-exec'      '#o0100'     execute (or search) by owner
     'group-read'      '#o0040'     read by group
     'group-write'     '#o0020'     write by group
     'group-exec'      '#o0010'     execute (or search) by group
     'other-read'      '#o0004'     read by others
     'other-write'     '#o0002'     write by others
     'other-exec'      '#o0001'     execute (or search) by others

     Also, several compound masks are supported for convenience:

     Permission set name   Octal mask   Description
     'owner'               '#o0700'     read, write, & execute by owner
     'group'               '#o0070'     read, write, & execute by group
     'other'               '#o0007'     read, write, & execute by others
     'read'                '#o0444'     read by anyone
     'write'               '#o0111'     write by anyone
     'exec'                '#o0777'     read, write, & execute by anyone

 -- procedure: file-mode+ file-mode ... --> file-mode
 -- procedure: file-mode- file-mode--_{a} file-mode--_{b} --> file-mode
 -- procedure: file-mode=? file-mode--_{a} file-mode--_{b} --> boolean
 -- procedure: file-mode<=? file-mode--_{a} file-mode--_{b} --> boolean
 -- procedure: file-mode>=? file-mode--_{a} file-mode--_{b} --> boolean
     'File-mode+' returns a file mode that contains all of the
     permissions specified in any of its arguments.  'File-mode-'
     returns a file mode that contains all of FILE-MODE-_{A}'s
     permissions not in FILE-MODE-_{B}.  'File-mode=?' tests whether two
     file modes are the same.  'File-mode<=?' returns true if each
     successive file mode argument has the same or more permissions as
     the previous one.  'File-mode>=?' returns true if each successive
     file mode argument has the same or fewer permissions as the
     previous one.

 -- procedure: file-mode->integer file-mode --> integer
 -- procedure: integer->file-mode integer --> file-mode
     These convert between file mode objects and Unix file mode masks as
     integers.  The integer representations may or may not be the masks
     used by the underlying operating system.


File: scheme48.info,  Node: POSIX time,  Next: POSIX I/O utilities,  Prev: POSIX file system access,  Up: POSIX interface

8.7 Time
========

A "time" record contains an integer that represents a time as the number
of seconds since the Unix epoch (00:00:00 GMT, January 1, 1970).  These
procedures for operating on time records are in the structures
'posix-time' & 'posix'.

 -- procedure: make-time seconds --> time
 -- procedure: current-time --> time
 -- procedure: time? object --> boolean
 -- procedure: time-seconds time --> integer
     'Make-time' & 'current-time' construct time records; 'make-time'
     uses the number of seconds that is its argument, and 'current-time'
     uses the current number of seconds since the epoch.  'Time?' is the
     disjoint type predicate for time objects.  'Time-seconds' returns
     the number of seconds recorded by TIME.

 -- procedure: time=? time--_{a} time--_{b} --> boolean
 -- procedure: time<? time--_{a} time--_{b} --> boolean
 -- procedure: time<=? time--_{a} time--_{b} --> boolean
 -- procedure: time>? time--_{a} time--_{b} --> boolean
 -- procedure: time>=? time--_{a} time--_{b} --> boolean
     Various time comparators.  'Time=?' returns true if its two
     arguments represent the same number of seconds since the epoch.
     'Time<?', 'time<=?', 'time>?', & 'time>=' return true if their
     arguments are monotonically increasing, monotonically
     non-decreasing, monotonically decreasing, or monotonically
     non-increasing, respectively.

 -- procedure: time->string time --> string
     Returns a string representation of TIME in the format of '"DDD MMM
     HH:MM:SS YYYY"'.  For example,

          (time->string (make-time 1234567890))
              => "Fri Feb 13 18:31:30 2009"

     *Note:* The string has a newline suffix.


File: scheme48.info,  Node: POSIX I/O utilities,  Next: POSIX regular expressions,  Prev: POSIX time,  Up: POSIX interface

8.8 I/O utilities
=================

These procedures for manipulating pipes and ports built on file
descriptors are provided by the structures 'posix-i/o' & 'posix'.

 -- procedure: open-pipe --> [input-port output-port]
     Creates a pipe and returns the two ends of the pipe as an input
     port & an output port.

   A "file descriptor port" (or "fd-port") is a port or a channel (*note
Channels::) that reads from or writes to an OS file descriptor.  File
descriptor ports are returned by the standard Scheme procedures
'open-input-file' & 'open-output-file' as well as the procedures
'open-file' & 'open-pipe' from this POSIX interface.

 -- procedure: fd-port? port --> boolean
 -- procedure: port->fd port --> integer or '#f'
     'Fd-port?' returns true if PORT is a port that reads from or writes
     to a file descriptor, or false if not.  'Port->fd' returns the file
     descriptor that PORT reads from or writes to, if it is a file
     descriptor port, or '#f' if it is not.  It is an error to pass a
     value that is not a port to either of these procedures.

     *Note:* Channels may _not_ be passed to these procedures.  To
     access a channel's file descriptor, use 'channel-os-index'; *note
     Channels:: for more details.

 -- procedure: remap-file-descriptors! fd-spec ... --> unspecified
     Reassigns file descriptors to ports.  Each FD-SPEC specifies what
     port is to be mapped to what file descriptor: the first port gets
     file descriptor '0'; the second, '1'; and so on.  An FD-SPEC is
     either a port that reads from or writes to a file descriptor or
     '#f'; in the latter case, the corresponding file descriptor is not
     used.  Any open ports not listed are marked _close-on-exec_.  The
     same port may be moved to multiple new file descriptors.

     For example,

          (remap-file-descriptors! (current-output-port)
                                   #f
                                   (current-input-port))

     moves the current output port to file descriptor '0' (i.e. 'stdin')
     and the current input port to file descriptor '2' (i.e. 'stderr').
     File descriptor '1' ('stdout') is not mapped to anything, and all
     other open ports (including anything that had the file descriptor
     '1') are marked _close-on-exec_.

 -- procedure: dup fd-port --> fd-port
 -- procedure: dup-switching-mode fd-port --> fd-port
 -- procedure: dup2 fd-port fdes --> fd-port
     These change FD-PORT's file descriptor and return new ports that
     have the ports' old file descriptors.  'Dup' uses the lowest unused
     file descriptor; 'dup2' uses the one provided.
     'Dup-switching-mode' is the same as 'dup' except that the returned
     port is an input port if the argument was an output port and vice
     versa.  If any existing port uses the file descriptor passed to
     'dup2', that port is closed.

 -- procedure: close-all-port port-or-channel ... --> unspecified
     Closes all ports or channels not listed as arguments.

 -- procedure: close-on-exec? channel --> boolean
 -- procedure: set-close-on-exec?! channel boolean --> unspecified
     These access the boolean flag that specifies whether CHANNEL will
     be closed when a new program is 'exec''d.

 -- procedure: i/o-flags fd-port --> file-options
 -- procedure: set-i/o-flags! fd-port file-options --> unspecified
     These access various file options (*note POSIX file system
     access::) for FD-PORT.  The options that may be read are 'append',
     'nonblocking', 'read-only', 'read-write', and 'write-only'; only
     the 'append' and 'nonblocking' options can be written.

 -- procedure: port-is-a-terminal? port --> boolean
 -- procedure: port-terminal-name port --> string or '#f'
     'Port-is-a-terminal?' returns true of PORT is a port that has an
     underlying file descriptor associated with a terminal.  For such
     ports, 'port-terminal-name' returns the name of the terminal; for
     all others, it returns '#f'.

     *Note:* These procedures accept only ports, not channels.


File: scheme48.info,  Node: POSIX regular expressions,  Next: POSIX C to Scheme correspondence,  Prev: POSIX I/O utilities,  Up: POSIX interface

8.9 Regular expressions
=======================

The procedures in this section provide access to POSIX regular
expression matching.  The regular expression syntax and semantics are
far too complex to be described here.

   *Note:* Because the C interface uses ASCII 'NUL' bytes to mark the
ends of strings, patterns & strings that contain 'NUL' characters will
not work correctly.

8.9.1 Direct POSIX regular expression interface
-----------------------------------------------

The first interface to regular expressions is a thin layer over the
interface that POSIX provides.  It is exported by the structures
'posix-regexps' & 'posix'.

 -- procedure: make-regexp string option ... --> regexp
 -- procedure: regexp? object --> boolean
     'Make-regexp' creates a regular expression with the given string
     pattern.  The arguments after STRING specify various options for
     the regular expression; see 'regexp-option' below.  The regular
     expression is not compiled until it is matched against a string, so
     any errors in the pattern string will not be reported until that
     point.  'Regexp?' is the disjoint type predicate for regular
     expression objects.

 -- syntax: regexp-option name --> regexp-option
     Evaluates to a regular expression option, suitable to be passed to
     'make-regexp', with the given name.  The possible option names are:

     'extended'
          use the extended patterns
     'ignore-case'
          ignore case differences when matching
     'submatches'
          report submatches
     'newline'
          treat newlines specially

 -- procedure: regexp-match regexp string start submatches? starts-line?
          ends-line? --> boolean or list of matches
     'Regexp-match' matches REGEXP against the characters in STRING,
     starting at position START.  If the string does not match the
     regular expression, 'regexp-match' returns '#f'.  If the string
     does match, then a list of match records is returned if SUBMATCHES?
     is true or '#t' if SUBMATCHES? is false.  The first match record
     gives the location of the substring that matched REGEXP.  If the
     pattern in REGEXP contained submatches, then the submatches are
     returned in order, with match records in the positions where
     submatches succeeded and '#f' in the positions where submatches
     failed.

     STARTS-LINE? should be true if STRING starts at the beginning of a
     line, and ENDS-LINE? should be true if it ends one.

 -- procedure: match? object --> boolean
 -- procedure: match-start match --> integer
 -- procedure: match-end match --> integer
 -- procedure: match-submatches match --> alist
     'Match?' is the disjoint type predicate for match records.  Match
     records contain three values: the beginning & end of the substring
     that matched the pattern and an association list of submatch keys
     and corresponding match records for any named submatches that also
     matched.  'Match-start' returns the index of the first character in
     the matching substring, and 'match-end' gives the index of the
     first character after the matching substring.  'Match-submatches'
     returns the alist of submatches.

8.9.2 High-level regular expression construction
------------------------------------------------

This section describes a functional interface for building regular
expressions and matching them against strings, higher-level than the
direct POSIX interface.  The matching is done using the POSIX regular
expression package.  Regular expressions constructed by procedures
listed here are compatible with those in the previous section; that is,
they satisfy the predicate 'regexp?' from the 'posix-regexps' structure.
These names are exported by the structure 'regexps'.

8.9.2.1 Character sets
......................

Character sets may be defined using a list of characters and strings,
using a range or ranges of characters, or by using set operations on
existing character sets.

 -- procedure: set char-or-string ... --> char-set-regexp
 -- procedure: range low-char high-char --> char-set-regexp
 -- procedure: ranges low-char high-char ... --> char-set-regexp
 -- procedure: ascii-range low-char high-char --> char-set-regexp
 -- procedure: ascii-ranges low-char high-char ... --> char-set-regexp
     'Set' returns a character set that contains all of the character
     arguments and all of the characters in all of the string arguments.
     'Range' returns a character set that contains all characters
     between LOW-CHAR and HIGH-CHAR, inclusive.  'Ranges' returns a set
     that contains all of the characters in the given set of ranges.
     'Range' & 'ranges' use the ordering imposed by 'char->integer'.
     'Ascii-range' & 'ascii-ranges' are like 'range' & 'ranges', but
     they use the ASCII ordering.  'Ranges' & 'ascii-ranges' must be
     given an even number of arguments.  It is an error for a HIGH-CHAR
     to be less than the preceding LOW-CHAR in the appropriate ordering.

 -- procedure: negate char-set --> char-set-regexp
 -- procedure: union char-set--_{a} char-set--_{b} --> char-set-regexp
 -- procedure: intersection char-set--_{a} char-set--_{b} -->
          char-set-regexp
 -- procedure: subtract char-set--_{a} char-set--_{b} -->
          char-set-regexp
     Set operations on character sets.  'Negate' returns a character set
     of all characters that are not in CHAR-SET.  'Union' returns a
     character set that contains all of the characters in CHAR-SET-_{A}
     and all of the characters in CHAR-SET-_{B}.  'Intersection' returns
     a character set of all of the characters that are in both
     CHAR-SET-_{A} and CHAR-SET-_{B}.  'Subtract' returns a character
     set of all the characters in CHAR-SET-_{A} that are not also in
     CHAR-SET-_{B}.

 -- character set: lower-case = '(set "abcdefghijklmnopqrstuvwxyz")'
 -- character set: lower-case = '(set "abcdefghijklmnopqrstuvwxyz")'
 -- character set: upper-case = '(set "ABCDEFGHIJKLMNOPQRSTUVWXYZ")'
 -- character set: alphabetic = '(union lower-case upper-case)'
 -- character set: numeric = '(set "0123456789")'
 -- character set: alphanumeric = '(union alphabetic numeric)'
 -- character set: punctuation = '(set
          "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~")'
 -- character set: graphic = '(union alphanumeric punctuation)'
 -- character set: printing = '(union graphic (set #\space))'
 -- character set: control = '(negate printing)'
 -- character set: blank = '(set #\space (ascii->char 9)) ; ASCII 9 =
          TAB'
 -- character set: whitespace = '(union (set #\space) (ascii-range 9
          13))'
 -- character set: hexdigit = '(set "0123456789ABCDEF")'
     Predefined character sets.

8.9.2.2 Anchoring
.................

 -- procedure: string-start --> regexp
 -- procedure: string-end --> regexp
     'String-start' returns a regular expression that matches the
     beginning of the string being matched against; 'string-end' returns
     one that matches the end.

8.9.2.3 Composite expressions
.............................

 -- procedure: sequence regexp ... --> regexp
 -- procedure: one-of regexp ... --> regexp
     'Sequence' returns a regular expression that matches concatenation
     of all of its arguments; 'one-of' returns a regular expression that
     matches any one of its arguments.

 -- procedure: text string --> regexp
     Returns a regular expression that matches exactly the characters in
     STRING, in order.

 -- procedure: repeat regexp --> regexp
 -- procedure: repeat count regexp --> regexp
 -- procedure: repeat min max regexp --> regexp
     'Repeat' returns a regular expression that matches zero or more
     occurrences of its REGEXP argument.  With only one argument, the
     result will match REGEXP any number of times.  With two arguments,
     i.e. one COUNT argument, the returned regular expression will match
     REGEXP exactly that number of times.  The final case will match
     from MIN to MAX repetitions, inclusive.  MAX may be '#f', in which
     case there is no maximum number of matches.  COUNT & MIN must be
     exact, non-negative integers; MAX should be either '#f' or an
     exact, non-negative integer.

8.9.2.4 Case sensitivity
........................

Regular expressions are normally case-sensitive, but case sensitivity
can be manipulated simply.

 -- procedure: ignore-case regexp --> regexp
 -- procedure: use-case regexp --> regexp
     The regular expression returned by 'ignore-case' is identical to
     its argument except that the case will be ignored when matching.
     The value returned by 'use-case' is protected from future
     applications of 'ignore-case'.  The expressions returned by
     'use-case' and 'ignore-case' are unaffected by any enclosing uses
     of these procedures.

     By way of example, the following matches '"ab"', but not '"aB"',
     '"Ab"', or '"AB"':

          (text "ab")

     while

          (ignore-case (text "ab"))

     matches all of those, and

          (ignore-case (sequence (text "a")
                                 (use-case (text "b"))))

     matches '"ab"' or '"Ab"', but not '"aB"' or '"AB"'.

8.9.2.5 Submatches and matching
...............................

A subexpression within a larger expression can be marked as a submatch.
When an expression is matched against a string, the success or failure
of each submatch within that expression is reported, as well as the
location of the substring matched by each successful submatch.

 -- procedure: submatch key regexp --> regexp
 -- procedure: no-submatches regexp --> regexp
     'Submatch' returns a regular expression that is equivalent to
     REGEXP in every way except that the regular expression returned by
     'submatch' will produce a submatch record in the output for the
     part of the string matched by REGEXP.  'No-submatches' returns a
     regular expression that is equivalent to REGEXP in every respect
     except that all submatches generated by REGEXP will be ignored &
     removed from the output.

 -- procedure: any-match? regexp string --> boolean
 -- procedure: exact-match? regexp string --> boolean
 -- procedure: match regexp string --> match or '#f'
     'Any-match?' returns '#t' if STRING matches REGEXP or contains a
     substring that does, or '#f' if otherwise.  'Exact-match?' returns
     '#t' if STRING matches REGEXP exactly, or '#f' if it does not.

     'Match' returns '#f' if STRING does not match REGEXP, or a match
     record if it does, as described in the previous section.  Matching
     occurs according to POSIX. The match returned is the one with the
     lowest starting index in STRING.  If there is more than one such
     match, the longest is returned.  Within that match, the longest
     possible submatches are returned.

     All three matching procedures cache a compiled version of REGEXP.
     Subsequent calls with the same input regular expression will be
     more efficient.

   Here are some examples of the high-level regular expression
interface:

     (define pattern (text "abc"))

     (any-match? pattern "abc")            => #t
     (any-match? pattern "abx")            => #f
     (any-match? pattern "xxabcxx")        => #t

     (exact-match? pattern "abc")          => #t
     (exact-match? pattern "abx")          => #f
     (exact-match? pattern "xxabcxx")      => #f

     (let ((m (match (sequence (text "ab")
                               (submatch 'foo (text "cd"))
                               (text "ef")))
              "xxabcdefxx"))
       (list m (match-submatches m)))
         => (#{Match 3 9} ((foo . #{Match 5 7})))

     (match-submatches
      (match (sequence (set "a")
                       (one-of (submatch 'foo (text "bc"))
                               (submatch 'bar (text "BC"))))
             "xxxaBCd"))
         => ((bar . #{Match 4 6}))


File: scheme48.info,  Node: POSIX C to Scheme correspondence,  Prev: POSIX regular expressions,  Up: POSIX interface

8.10 C to Scheme correspondence
===============================

'access'
     'accessible?'
'chdir'
     'set-working-directory!'
'close'
     'close-input-port, close-output-port, close-channel, close-socket'
'closedir'
     'close-directory-stream'
'creat'
     'open-file'
'ctime'
     'time->string'
'dup'
     'dup, dup-switching-mode'
'dup2'
     'dup2'
'exec[l|v][e|p|eps]'
     'exec, exec-with-environment, exec-file,
     exec-file-with-environment, exec-with-alias'
'_exit'
     'exit'
'fcntl'
     'i/o-flags, set-i/o-flags!, close-on-exec?, set-close-on-exec?!'
'fork'
     'fork, fork-and-forget'
'fstat'
     'get-port-info'
'getcwd'
     'working-directory'
'getegid'
     'get-effective-group-id'
'getenv'
     'lookup-environment-variable, environment-alist'
'geteuid'
     'get-effective-user-id'
'getgid'
     'get-group-id'
'getgroups'
     'get-login-name'
'getpid'
     'get-process-id'
'getppid'
     'get-parent-process-id'
'getuid'
     'get-user-id'
'isatty'
     'port-is-a-terminal?'
'link'
     'link'
'lstat'
     'get-file/link-info'
'mkdir'
     'make-directory'
'mkfifo'
     'make-fifo'
'open'
     'open-file'
'opendir'
     'open-directory-stream'
'pipe'
     'open-pipe'
'read'
     'read-char, read-block'
'readdir'
     'read-directory-stream'
'rename'
     'rename'
'rmdir'
     'remove-directory'
'setgid'
     'set-group-id!'
'setuid'
     'set-user-id!'
'stat'
     'get-file-info'
'time'
     'current-time'
'ttyname'
     'port-terminal-name'
'umask'
     'set-file-creation-mask!'
'uname'
     'os-name, os-node-name, os-release-name, os-version-name,
     machine-name'
'unlink'
     'unlink'
'waitpid'
     'wait-for-child-process'
'write'
     'write-char, write-block'


File: scheme48.info,  Node: Pre-Scheme,  Next: References,  Prev: POSIX interface,  Up: Top

9 Pre-Scheme: A low-level dialect of Scheme
*******************************************

Pre-Scheme [Kelsey 97] is a low-level dialect of Scheme, designed for
systems programming with higher-level abstractions.  For example, the
Scheme48 virtual machine is written in Pre-Scheme.  Pre-Scheme is a
particularly interesting alternative to C for many systems programming
tasks, because not only does it operate at about the same level as C,
but it also may be run in a regular high-level Scheme development with
no changes to the source, without resorting to low-level stack munging
with tools such as gdb.  Pre-Scheme also supports two _extremely_
important high-level abstractions of Scheme: macros and higher-order,
anonymous functions.  Richard Kelsey's Pre-Scheme compiler, based on his
PhD research on transformational compilation [Kelsey 89], compiles
Pre-Scheme to efficient C, applying numerous intermediate source
transformations in the process.

   This chapter describes details of the differences between Scheme and
Pre-Scheme, listings of the default environment and other packages
available to Pre-Scheme, the operation of Richard Kelsey's Pre-Scheme
compiler, and how to run Pre-Scheme code as if it were Scheme in a
regular Scheme environment.

* Menu:

* Differences between Pre-Scheme & Scheme::
* Pre-Scheme type specifiers::
* Standard Pre-Scheme environment::
* More Pre-Scheme packages::
* Invoking the Pre-Scheme compiler::
* Example Pre-Scheme compiler usage::
* Running Pre-Scheme as Scheme::


File: scheme48.info,  Node: Differences between Pre-Scheme & Scheme,  Next: Pre-Scheme type specifiers,  Up: Pre-Scheme

9.1 Differences between Pre-Scheme & Scheme
===========================================

Pre-Scheme is often considered either a dialect of Scheme or a subset of
Scheme.  However, there are several very important fundamental
differences between the semantics of Pre-Scheme & Scheme to detail.

*There is no garbage collector in Pre-Scheme.*
     All memory management is manual, as in C, although there are two
     levels to memory management, for higher- and lower-level purposes:
     pointers & addresses.  Pointers represent higher-level data that
     are statically checked for type coherency, such as vectors of a
     certain element type, or strings.  Addresses represent direct,
     low-level memory indices.

*Pre-Scheme has no closures.*
     'Lambda' expressions that would require full closures at run-time
     -- e.g., those whose values are stored in the heap -- are not
     permitted in Pre-Scheme.  However, the Pre-Scheme compiler can
     hoist many 'lambda' expressions to the top level, removing the need
     of closures for them.  (Closures would be much less useful in the
     absence of garbage collection, in any case.)  If the Pre-Scheme
     compiler is unable to move a 'lambda' to a place where it requires
     no closure, it signals an error to the user.

*Tail call optimization is not universal.*
     The Pre-Scheme compiler optimizes tail calls where it is possible
     -- typically, just in local loops and top-level procedures that are
     not exported from the package, but there are other heuristics --,
     but it is not universal.  Programmers may force tail call
     optimization with Pre-Scheme's 'goto' special form (*note Tail call
     optimization in Pre-Scheme::), but, in situations where the
     compiler would not have optimized the tail call, this can make the
     generated code have to jump through many hoops to be a tail call --
     often necessitating code bloat, because the code of the tail-called
     procedure is integrated into the caller's driver loop --; and,
     where the compiler would have otherwise optimized the tail call,
     'goto' has no effect anyway.

*Types are strictly verified with Hindley-Milner type inference.*
     The types of Pre-Scheme programs are statically verified based on
     Hindley-Milner type inference, with some modifications specific to
     Pre-Scheme.  Type information is _not_ retained at run-time; any
     tagging must be performed explicitly.

*Pre-Scheme does not support first-class continuations.*
     There is no 'call-with-current-continuation' or other continuation
     manipulation interface.  It has been suggested that downward-only
     continuations, based on C's 'setjmp' & 'longjmp', might be
     implemented in the future, but this is not yet the case.(1)

*The full numeric tower of R5RS is not supported by Pre-Scheme.*
     Pre-Scheme's only numeric types are fixnums and flonums, with
     precision determined by the architecture on which the Pre-Scheme
     code runs.  Fixnums are translated to C as the 'long' type; flonums
     are translated as the 'float' type.

*Top-level Pre-Scheme code is evaluated at compile-time.*
     Closures actually _are_ available, as long as they may be
     eliminated before run-time.  Code evaluated at compile-time also
     does not require satisfaction of strict static typing.  Moreover,
     certain procedures, such as 'vector-length', are available only at
     compile-time.

   ---------- Footnotes ----------

   (1) It may be possible to use Pre-Scheme's C FFI to manually use
'setjmp' & 'longjmp', but the author of this manual cannot attest to
this working.


File: scheme48.info,  Node: Pre-Scheme type specifiers,  Next: Standard Pre-Scheme environment,  Prev: Differences between Pre-Scheme & Scheme,  Up: Pre-Scheme

9.2 Type specifiers
===================

Although Pre-Scheme's static type system is based mostly on
Hindley-Milner type inference, with as little explicit type information
as possible, there are still places where it is necessary to specify
types explicitly; for example, *note Pre-Scheme access to C functions
and macros::.  There are several different kinds of types with different
syntax:

'TYPE-NAME'
     Symbols denote either record type or base types.  Record types are
     defined with the 'define-record-type' special form described later;
     the following base types are defined:

     'integer'
          Fixed-size integers (fixnums).  This type is translated into C
          as 'long'.  The actual size depends on the size of C's 'long',
          which on most architectures is 32 bits.

     'float'
          Floating-point data.  This type translates to C as 'double'.

     'null'
          Type which has no value.  The 'null' type translates to the C
          'void' type.

     'unit'
          Type which has one value.  Actually, this, too, translates to
          C's 'void', so that it has one value is not strictly true.

     'boolean'
          Booleans translate to the C 'char' type.  '#t' is emitted as
          'TRUE', and '#f', as 'FALSE'; these are usually the same as
          '1' & '0', respectively.

     'input-port'
     'output-port'
          I/O ports.  On Unix, since Pre-Scheme uses 'stdio', these are
          translated to 'FILE *'s, 'stdio' file streams.

     'char'
          Characters.  The size of characters is dependent on the
          underlying C compiler's implementation of the 'char' type.

     'address'
          Simple addresses for use in Pre-Scheme's low-level memory
          manipulation primitives (*note Low-level Pre-Scheme memory
          manipulation::); see that section for more details.

'(=> (ARGUMENT-TYPE ...) RETURN-TYPE ...)'
     The types of procedures, known as 'arrow' types.

'(^ TYPE)'
     The type of pointers that point to TYPE.  Note that these are
     distinct from the address type.  Pointer types are statically
     verified to be coherent data, with no defined operations except for
     accessing offsets in memory from the pointer -- i.e. operations
     such as 'vector-ref' --; addresses simply index bytes, on which
     only direct dereferencing, but also arbitrary address arithmetic,
     is available.  Pointers and addresses are _not_ interchangeable,
     and and there is no way to convert between them, as that would
     break the type safety of Pre-Scheme pointers.

'(tuple TYPE ...)'
     Multiple value types, internally used for argument & return types.


File: scheme48.info,  Node: Standard Pre-Scheme environment,  Next: More Pre-Scheme packages,  Prev: Pre-Scheme type specifiers,  Up: Pre-Scheme

9.3 Standard environment
========================

Pre-Scheme programs usually open the 'prescheme' structure.  There are
several other structures built-in to Pre-Scheme as well, described in
the next section.  This section describes the 'prescheme' structure.

* Menu:


* Scheme bindings in Pre-Scheme::		Bindings from R5RS
* Tail call optimization in Pre-Scheme::
* Pre-Scheme bitwise manipulation::
* Compound Pre-Scheme data manipulation::
* Pre-Scheme error handling::
* Input & output in Pre-Scheme::
* Pre-Scheme access to C functions and macros::


File: scheme48.info,  Node: Scheme bindings in Pre-Scheme,  Next: Tail call optimization in Pre-Scheme,  Up: Standard Pre-Scheme environment

9.3.1 Scheme bindings
---------------------

Bindings for all the names specified here from R5RS Scheme are available
in Pre-Scheme.  The remainder of the sections after this one detail
Pre-Scheme specifics that are not a part of Scheme.

 -- syntax: define name value
 -- syntax: define (name . argument-list) value
 -- syntax: if condition consequent [alternate]
 -- syntax: let ((name expression) ...) body
 -- syntax: let* ((name expression) ...) body
 -- syntax: and conjunct ...
 -- syntax: or disjunct ...
 -- syntax: cond cond-clause ...
 -- syntax: do ((name init-exp [step-exp]) ...) (test-exp [return-exp])
          body
     These special forms & macros are all unchanged from their R5RS
     specifications.

 -- syntax: define-syntax name transformer-expression [aux-names]
 -- syntax: let-syntax ((name transformer-expression) ...) body
 -- syntax: letrec-syntax ((name transformer-expression) ...) body
     Pre-Scheme's macro facility is exactly the same as Scheme48's.
     TRANSFORMER-EXPRESSION may be either a 'syntax-rules' or an
     explicit renaming transformer, just as in Scheme48; in the latter
     case, it is evaluated either in a standard Scheme environment or
     however the 'for-syntax' clause specified of the package in whose
     code the transformer appeared.  For details on the extra AUX-NAMES
     operand to 'define-syntax', *note Explicit renaming macros::.

 -- procedure: not boolean --> boolean
 -- procedure: eq? value--_{a} value--_{b} --> boolean
 -- procedure: char=? char--_{a} char--_{b} --> boolean
 -- procedure: char<? char--_{a} char--_{b} --> boolean
 -- procedure: values value ... --> values
 -- procedure: call-with-values producer consumer --> values
 -- procedure: current-input-port --> input-port
 -- procedure: current-output-port --> output-port
     These procedures are all unchanged from their R5RS specifications.

 -- procedure: + addend ... --> integer
 -- procedure: - integer --> integer
 -- procedure: - minuend subtrahend --> integer
 -- procedure: * multiplicand ... --> integer
 -- procedure: = integer--_{a} integer--_{b} --> boolean
 -- procedure: < integer--_{a} integer--_{b} --> boolean
 -- procedure: > integer--_{a} integer--_{b} --> boolean
 -- procedure: <= integer--_{a} integer--_{b} --> boolean
 -- procedure: >= integer--_{a} integer--_{b} --> boolean
 -- procedure: min integer_{1} integer_{2} ... --> integer
 -- procedure: max integer_{1} integer_{2} ... --> integer
 -- procedure: abs integer --> integer
 -- procedure: quotient divisor dividend --> integer
 -- procedure: remainder divisor dividend --> integer
 -- procedure: expt base exponent --> integer
     These numerical operations are all unchanged from their R5RS
     counterparts, except that they are applicable only to fixnums, not
     to flonums, and they always return fixnums.


File: scheme48.info,  Node: Tail call optimization in Pre-Scheme,  Next: Pre-Scheme bitwise manipulation,  Prev: Scheme bindings in Pre-Scheme,  Up: Standard Pre-Scheme environment

9.3.2 Tail call optimization
----------------------------

 -- syntax: goto procedure argument ...
     The Pre-Scheme compiler can be forced to optimize tail calls, even
     those it would not have otherwise optimized, by use of the 'goto'
     special form, rather than simple procedure calls.  In every respect
     other than tail call optimization, this is equivalent to calling
     PROCEDURE with the given arguments.  Note, however, that uses of
     'goto' may cause code to blow up if the Pre-Scheme compiler had
     reason not to optimize the tail call were it not for the 'goto': it
     may need to merge the tail-called procedure into the caller's code.


File: scheme48.info,  Node: Pre-Scheme bitwise manipulation,  Next: Compound Pre-Scheme data manipulation,  Prev: Tail call optimization in Pre-Scheme,  Up: Standard Pre-Scheme environment

9.3.3 Bitwise manipulation
--------------------------

Pre-Scheme provides basic bitwise manipulation operators.

 -- procedure: bitwise-and integer--_{a} integer--_{b} --> integer
 -- procedure: bitwise-ior integer--_{a} integer--_{b} --> integer
 -- procedure: bitwise-xor integer--_{a} integer--_{b} --> integer
 -- procedure: bitwise-not integer --> integer
     Bitwise boolean logical operations.

 -- procedure: shift-left integer count --> integer
 -- procedure: arithmetic-shift-right integer count --> integer
 -- procedure: logical-shift-right integer count --> integer
     Three ways to shift bit strings: 'shift-left' shifts INTEGER left
     by COUNT, 'arithmetic-shift-right' shifts INTEGER right by COUNT
     arithmetically, and 'logical-shift-right' shifts INTEGER right by
     COUNT logically.


File: scheme48.info,  Node: Compound Pre-Scheme data manipulation,  Next: Pre-Scheme error handling,  Prev: Pre-Scheme bitwise manipulation,  Up: Standard Pre-Scheme environment

9.3.4 Compound data manipulation
--------------------------------

Pre-Scheme has somewhat lower-level vector & string facilities than
Scheme, with more orientation towards static typing.  It also provides a
statically typed record facility, which translates to C structs, though
not described here, as it is not in the 'prescheme' structure; *note
Pre-Scheme record types::.

 -- procedure: make-vector length init --> vector
 -- procedure: vector-length vector --> integer
 -- procedure: vector-ref vector index --> value
 -- procedure: vector-set! vector index value --> unit
     Vectors in Pre-Scheme are almost the same as vectors in regular
     Scheme, but with a few differences.  'Make-vector' initializes what
     it returns with null pointers (see below); it uses the _required_
     (unlike Scheme) INIT argument only to determine the type of the
     vector: vectors are statically typed; they can contain only values
     that have the same static type as INIT.  'Vector-length' is
     available only at the top level, where calls to it can be evaluated
     at compile-time; vectors do not at run-time store their lengths.
     Vectors must also be explicitly deallocated.

     *Warning:* As in C, there is _no_ vector bounds checking at
     run-time.

 -- procedure: make-string length --> string
 -- procedure: string-length string --> integer
 -- procedure: string-ref string index --> char
 -- procedure: string-set! string index char --> unit
     Strings in Pre-Scheme are the nearly same as strings in R5RS
     Scheme.  The only three differences here are that 'make-string'
     accepts exactly one argument, strings must be explicitly
     deallocated, and strings are 'nul'-terminated: 'string-length'
     operates by scanning for the first ASCII 'nul' character in a
     string.

     *Warning:* As in C, there is _no_ string bounds checking at
     run-time.

 -- procedure: deallocate pointer --> unit
     Deallocates the memory pointed to by 'pointer'.  This is necessary
     at the end of a string, vector, or record's life, as Pre-Scheme
     data are not automatically garbage-collected.

 -- procedure: null-pointer --> null-pointer
 -- procedure: null-pointer? pointer --> boolean
     'Null-pointer' returns the distinguished null pointer object.  It
     corresponds with '0' in a pointer context or 'NULL' in C.
     'Null-pointer?' returns true if POINTER is a null pointer, or false
     if not.


File: scheme48.info,  Node: Pre-Scheme error handling,  Next: Input & output in Pre-Scheme,  Prev: Compound Pre-Scheme data manipulation,  Up: Standard Pre-Scheme environment

9.3.5 Error handling
--------------------

Pre-Scheme's method of error handling is similar to the most common one
in C: error codes.  There is an enumeration 'errors' of some error codes
commonly and portably encountered in Pre-Scheme.

 -- enumeration: errors
          (define-enumeration errors
            (no-errors
             parse-error
             file-not-found
             out-of-memory
             invalid-port))
     Each enumerand has the following meaning:

     '(enum errors no-errors)'
          Absence of error: success.

     '(enum errors parse-error)'
          Any kind of parsing error.  The Scheme48 VM uses this when
          someone attempts to resume a malformed suspended heap image.

     '(enum errors file-not-found)'
          Used when an operation that operates on a file given a string
          filename found that the file for that filename was absent.

     '(enum errors out-of-memory)'
          When there is no more memory to allocate.

     '(enum errors invalid-port)'
          Unused.

 -- procedure: error-string error-status --> string
     Returns a string describing the meaning of the 'errors' enumerand
     ERROR-STATUS.

 -- procedure: error message irritant ...
     Signals a fatal error with the given message & related irritants
     and halts the program.  On Unix, the program's exit code is -1.


File: scheme48.info,  Node: Input & output in Pre-Scheme,  Next: Pre-Scheme access to C functions and macros,  Prev: Pre-Scheme error handling,  Up: Standard Pre-Scheme environment

9.3.6 Input & output
--------------------

Pre-Scheme's I/O facilities are somewhat different from Scheme's, given
the low level and the static type strictness.  There is no exception
mechanism in Pre-Scheme; everything is maintained by returning a status
token, as in C. Pre-Scheme's built-in I/O facilities are buffered.  (1)
(*note Low-level Pre-Scheme memory manipulation::, for two other I/O
primitives, 'read-block' & 'write-block', for reading & writing blocks
of direct memory.)

 -- procedure: open-input-file filename --> [port status]
 -- procedure: open-output-file filename --> [port status]
 -- procedure: close-input-port input-port --> status
 -- procedure: close-output-port output-port --> status
     'Open-input-file' & 'open-output-file' open ports for the given
     filenames.  They each return two values: the newly open port and an
     'errors' enumerand status.  Users of these procedures should always
     check the error status before proceeding to operate with the port.
     'Close-input-port' & 'close-output-port' close their port arguments
     and return the 'errors' enumerand status of the closing.

 -- procedure: read-char input-port --> [char eof? status]
 -- procedure: peek-char input-port --> [char eof? status]
 -- procedure: read-integer input-port --> [integer eof? status]
     'Read-char' reads & consumes a single character from its INPUT-PORT
     argument.  'Peek-char' reads, but does not consume, a single
     character from INPUT-PORT.  'Read-integer' parses an integer
     literal, including sign.  All of these also return two other
     values: whether or not the file is at the end and any 'errors'
     enumerand status.  If any error occurred, the first two values
     returned should be ignored.  If STATUS is '(enum errors
     no-errors)', users of these three procedures should then check
     EOF?; it is true if INPUT-PORT was at the end of the file with
     nothing more left to read and false otherwise.  Finally, if both
     STATUS is '(enum errors no-errors)' and EOF? is false, the first
     value returned may be safely used.

 -- procedure: write-char char output-port --> status
 -- procedure: newline output-port --> status
 -- procedure: write-string string output-port --> status
 -- procedure: write-integer integer output-port --> status
     These all write particular elements to their OUTPUT-PORT arguments.
     'Write-char' writes individual characters.  'Newline' writes
     newlines (line-feed, or ASCII codepoint 10, on Unix).
     'Write-string' writes the contents of STRING.  'Write-integer'
     writes an ASCII representation of INTEGER to port, suitable to be
     read by 'read-integer'.  These all return an 'errors' enumerand
     status.  If it is 'no-errors', the write succeeded.

 -- procedure: force-output output-port --> status
     Forces all buffered output in OUTPUT-PORT.  STATUS tells whether or
     not the operation was successful.

   ---------- Footnotes ----------

   (1) Scheme48's VM does not use Pre-Scheme's built-in I/O facilities
to implement channels (*note Channels::) -- it builds its own
lower-level facilities that are still OS-independent, but, because
they're written individually for different OSs, they integrate better as
low-level I/O channels with the OS. On Unix, the Scheme48 VM uses file
descriptors; Pre-Scheme's built-in I/O uses 'stdio'.  Scheme48's VM uses
Pre-Scheme's built-in I/O only to read heap images.


File: scheme48.info,  Node: Pre-Scheme access to C functions and macros,  Prev: Input & output in Pre-Scheme,  Up: Standard Pre-Scheme environment

9.3.7 Access to C functions and macros
--------------------------------------

 -- syntax: external c-name ps-type --> procedure
     Special form for accessing C functions & macros.  Calls in
     Pre-Scheme to the resulting procedure are compiled to calls in C to
     the function or macro named by C-NAME, which should be a string.
     PS-TYPE is the Pre-Scheme type (*note Pre-Scheme type specifiers::)
     that the procedure should have, which is necessary for type
     inference.


File: scheme48.info,  Node: More Pre-Scheme packages,  Next: Invoking the Pre-Scheme compiler,  Prev: Standard Pre-Scheme environment,  Up: Pre-Scheme

9.4 More Pre-Scheme packages
============================

Along with the 'prescheme' structure, there are several other structures
built-in to Pre-Scheme.

* Menu:


* Pre-Scheme floating point operation::
* Pre-Scheme record types::
* Multiple return values in Pre-Scheme::
* Low-level Pre-Scheme memory manipulation::


File: scheme48.info,  Node: Pre-Scheme floating point operation,  Next: Pre-Scheme record types,  Up: More Pre-Scheme packages

9.4.1 Floating point operation
------------------------------

Since Pre-Scheme's strict static type system would not permit
overloading of the arithmetic operators for integers & floats, it
provides a different set of operators for floats.  These names are all
exported by the 'ps-flonums' structure.

 -- procedure: fl+ augend addend ... --> float
 -- procedure: fl- float --> float
 -- procedure: fl- minuend subtrahend --> float
 -- procedure: fl* multiplier multiplicand ... --> float
 -- procedure: fl/ divisor dividend --> float
 -- procedure: fl= float--_{a} float--_{b} --> boolean
 -- procedure: fl< float--_{a} float--_{b} --> boolean
 -- procedure: fl> float--_{a} float--_{b} --> boolean
 -- procedure: fl<= float--_{a} float--_{b} --> boolean
 -- procedure: fl>= float--_{a} float--_{b} --> boolean
     All of these operations 'flOP' correspond as floating point
     variations of their OP integer equivalents.


File: scheme48.info,  Node: Pre-Scheme record types,  Next: Multiple return values in Pre-Scheme,  Prev: Pre-Scheme floating point operation,  Up: More Pre-Scheme packages

9.4.2 Record types
------------------

The 'ps-record-types' structure defines the following special form for
introducing record types.  Pre-Scheme record types are translated to C
as structs.

 -- syntax: define-record-type
          (define-record-type TYPE TYPE-DESCRIPTOR
            (CONSTRUCTOR ARGUMENT-FIELD-TAG ...)
            (FIELD-TAG_{1} FIELD-TYPE-SPEC_{1}
              FIELD-ACCESSOR_{1} [FIELD-MODIFIER_{1}])
            (FIELD-TAG_{2} FIELD-TYPE-SPEC_{2}
              FIELD-ACCESSOR_{2} [FIELD-MODIFIER_{2}])
            ...
            (FIELD-TAG_{N} FIELD-TYPE-SPEC_{N}
              FIELD-ACCESSOR_{N} [FIELD-MODIFIER_{N}])
     Defines a record type.  TYPE is mangled to the C struct type name
     (TYPE-DESCRIPTOR-NAME is unused unless running Pre-Scheme as
     Scheme).  CONSTRUCTOR is defined to construct a record of the new
     type and initialize the fields ARGUMENT-TYPE-FIELD ... with its
     arguments, respectively.  If it cannot allocate a sufficient
     quantity of memory, CONSTRUCTOR returns a null pointer.  The
     initial values of fields that are not passed to the constructor are
     undefined.  For each field FIELD-_{I} specified,

        * FIELD-_{I} is specified to have the type FIELD-TYPE-SPEC-_{I};

        * FIELD-ACCESSOR-_{I} is defined to be a procedure of one
          argument, a record of type TYPE-NAME, that returns the value
          of the field FIELD-_{I} of that record -- its type is defined
          to be '(=> (TYPE-NAME) FIELD-TYPE-SPEC--_{I})'; and

        * if present, FIELD-MODIFIER-_{I} is defined to be a procedure
          of two arguments, a record of type TYPE-NAME and a value of
          type FIELD-TYPE-SPEC, that assigns the value of the field
          FIELD-_{I} in its first argument to be the value of its second
          argument; its type is '(=> (TYPE-NAME FIELD-TYPE-SPEC) unit)'.

     Records must be deallocated explicitly when their lifetime has
     expired with 'deallocate'.


File: scheme48.info,  Node: Multiple return values in Pre-Scheme,  Next: Low-level Pre-Scheme memory manipulation,  Prev: Pre-Scheme record types,  Up: More Pre-Scheme packages

9.4.3 Multiple return values
----------------------------

Pre-Scheme support multiple return values, like in Scheme.  The only
difference is that one cannot operate on multiple return values as
lists, since Pre-Scheme does not have lists.  Multiple return values are
implemented in C as returning in C the first value and passing pointers
to the remaining values, which the function returning multiple values
assigns.  The 'prescheme' structure exports the two multiple return
value primitives, 'call-with-values' and 'values', but the 'ps-receive'
structure exports this macro for more conveniently binding multiple
return values.

 -- syntax: receive formals producer body
     Binds the 'lambda' parameter list FORMALS to the multiple values
     that PRODUCER returns, and evaluates BODY with the new variables
     bound.

          (receive FORMALS
                   PRODUCER
            BODY)
              ==
          (call-with-values
              (lambda () PRODUCER)
            (lambda FORMALS
              BODY))


File: scheme48.info,  Node: Low-level Pre-Scheme memory manipulation,  Prev: Multiple return values in Pre-Scheme,  Up: More Pre-Scheme packages

9.4.4 Low-level memory manipulation
-----------------------------------

Pre-Scheme is a low-level language.  It provides very low-level, direct
memory manipulation.  'Addresses' index a flat store of sequences of
bytes.  While Pre-Scheme 'pointers' are statically checked for data
coherency, allow no arbitrary arithmetic, and in general are high-level
abstract data to some extent, addresses are much lower-level, have no
statically checked coherency -- the values an address represents are
selected by what operation used to read or write from it --, permit
arbitrary address arithmetic, and are a much more concrete interface
into direct memory.  The 'ps-memory' structure exports these direct
memory manipulation primitives.

 -- procedure: allocate-memory size --> address
 -- procedure: deallocate-memory address --> unit
     'Allocate-memory' reserves a sequence of SIZE bytes in the store
     and returns an address to the first byte in the sequence.
     'Deallocate-memory' releases the memory at ADDRESS, which should
     have been the initial address of a contiguous byte sequence, as
     'allocate-memory' would return, not an offset address from such an
     initial address.

 -- procedure: unsigned-byte-ref address --> unsigned-byte
 -- procedure: unsigned-byte-set! address unsigned-byte --> unit
 -- procedure: word-ref address --> word
 -- procedure: word-set! address word --> unit
 -- procedure: flonum-ref address --> float
 -- procedure: flonum-set! address float --> unit
     Procedures for reading from & storing to memory.
     'Unsigned-byte-ref' & 'unsigned-byte-set!' access & store the first
     unsigned byte at ADDRESS.  'Word-ref' & 'word-set!' access & store
     the first word -- Pre-Scheme integer -- beginning at ADDRESS.
     'Flonum-ref' & 'flonum-set!' access & store 64-bit floats beginning
     at ADDRESS..

     *Bug:* 'Flonum-ref' & 'flonum-set!' are unimplemented in the
     Pre-Scheme-as-Scheme layer (*note Running Pre-Scheme as Scheme::).

 -- procedure: address? value --> boolean
     Disjoint type predicate for addresses.

     *Note:* 'Address?' is available _only_ at the top level, where code
     is evaluated at compile-time.  Do not use this in any place where
     it may be called at run-time.

 -- constant: null-address --> address
     The null address.  This is somewhat similar to the null pointer,
     except that it is an address.

     *Note:* One acquires the null _pointer_ by calling the _procedure_
     'null-pointer', whereas the constant value of the _binding_ named
     'null-address' is the null _address_.

 -- procedure: null-address? address --> boolean
     'Null-address?' returns true if ADDRESS is the null address and
     false if not.

 -- procedure: address+ address increment --> address
 -- procedure: address- address decrement --> address
 -- procedure: address-difference address--_{a} address--_{b} -->
          integer
     Address arithmetic operators.  'Address+' adds INCREMENT to
     ADDRESS; 'address-' subtracts DECREMENT from ADDRESS; and
     'address-difference' returns the integer difference between
     ADDRESS-_{A} and ADDRESS-_{B}.  For any ADDRESS-_{P} &
     ADDRESS-_{Q}, '(address+ ADDRESS--_{P} (address-difference
     ADDRESS--_{P} ADDRESS--_{Q}))' is equal to ADDRESS-_{Q}.

 -- procedure: address= address--_{a} address--_{b} --> boolean
 -- procedure: address< address--_{a} address--_{b} --> boolean
 -- procedure: address> address--_{a} address--_{b} --> boolean
 -- procedure: address<= address--_{a} address--_{b} --> boolean
 -- procedure: address>= address--_{a} address--_{b} --> boolean
     Address comparators.

 -- procedure: integer->address integer --> address
 -- procedure: address->integer address --> integer
     Integers and addresses, although not the same type, may be
     converted to and from each other; 'integer->address' &
     'address->integer' perform this conversion.  Note that Pre-Scheme
     _pointers_ may not be converted to addresses or integers, and the
     converse is also true.

 -- procedure: copy-memory! source-address target-address count --> unit
     Copies COUNT bytes starting at SOURCE-ADDRESS to TARGET-ADDRESS.
     This is similar to C's 'memcpy'.

 -- procedure: memory-equal? address--_{a} address--_{b} count -->
          boolean
     Compares the two sequences of COUNT bytes starting at addresses
     ADDRESS-_{A} & ADDRESS-_{B}.  It returns true if every byte is
     equal and false if not.

 -- procedure: char-pointer->string address size --> string
 -- procedure: char-pointer->nul-terminated-string address --> string
     'Char-pointer->string' returns a string with SIZE bytes from the
     contiguous sequence of bytes starting at ADDRESS.
     'Char-pointer->nul-terminated-string' does similarly, but it
     returns a string whose contents include every byte starting at
     ADDRESS until, but not including, the first 0 byte, i.e. ASCII nul
     character, following ADDRESS.

 -- procedure: read-block port address count --> [count-read eof?
          status]
 -- procedure: write-block port address count --> status
     'Read-block' attempts to read COUNT bytes from PORT into memory
     starting at ADDRESS.  'Write-block' attempts to write COUNT bytes
     to PORT from the contiguous sequence in memory starting at ADDRESS.
     'Read-block' returns three values: the number of bytes read,
     whether or not the read went to the end of the file, and the error
     status (*note Pre-Scheme error handling::).  'Write-block' returns
     the error status.


File: scheme48.info,  Node: Invoking the Pre-Scheme compiler,  Next: Example Pre-Scheme compiler usage,  Prev: More Pre-Scheme packages,  Up: Pre-Scheme

9.5 Invoking the Pre-Scheme compiler
====================================

Richard Kelsey's Pre-Scheme compiler is a whole-program compiler based
on techniques from his research in transformational compilation [Kelsey
89].  It compiles the restricted dialect of Scheme to efficient C, and
provides facilities for programmer direction in several optimizations.

9.5.1 Loading the compiler
--------------------------

There is a script, a Scheme48 command program (*note Command
programs::), that comes with Scheme48 to load the Pre-Scheme compiler,
which is in the file 'ps-compiler/load-ps-compiler.scm'.  It must be
loaded from the 'ps-compiler/' directory, from Scheme48's main
distribution, into the 'exec' package, after having loaded
'../scheme/prescheme/interface.scm' &
'../scheme/prescheme/package-defs.scm' into the 'config' package.  The
Pre-Scheme compiler takes some time to load, so it may be easier to load
it once and dump a heap image of the suspended command processor after
having loaded everything; *note Image-building commands::.

   To load the Pre-Scheme compiler and dump an image to the file
'ps-compiler.image' that contains 'prescheme-compiler' in the user
package, send this sequence of commands to the command processor while
in the 'ps-compiler/' directory of Scheme48's distribution:

     ,config ,load ../scheme/prescheme/interface.scm
     ,config ,load ../scheme/prescheme/package-defs.scm
     ,exec ,load load-ps-compiler.scm
     ,in prescheme-compiler prescheme-compiler
     ,user (define prescheme-compiler ##)
     ,dump ps-compiler.image "(Pre-Scheme)"

9.5.2 Calling the compiler
--------------------------

After having loaded the Pre-Scheme compiler, the 'prescheme-compiler'
structure is the front end to the compiler that exports the
'prescheme-compiler' procedure.

 -- procedure: prescheme-compiler structure-spec config-filenames
          init-name c-filename command ...
     Invokes the Pre-Scheme compiler.  CONFIG-FILENAMES contain module
     descriptions (*note Module system::) for the components of the
     program.  STRUCTURE-SPEC may be a symbol or a list of symbols,
     naming the important structure or structures.  All structures that
     it relies/they rely on are traced in the packages' 'open' clauses.
     Modules that are not traced in the dependency graph with root
     vertices of the given structure[s] are omitted from the output.
     C-FILENAME is a string naming the file to which the C code
     generated by the Pre-Scheme compiler should be emitted.  INIT-NAME
     is the name for an initialization routine, generated automatically
     by the Pre-Scheme compiler to initialize some top-level variables.
     The COMMAND arguments are used to control certain aspects of the
     compilation.  The following commands are defined:

     '(copy (STRUCTURE COPYABLE-PROCEDURE) ...)'
          Specifies that each the body of each COPYABLE-PROCEDURE from
          the respective STRUCTURE (from one of CONFIG-FILENAMES) may be
          integrated & duplicated.

     '(no-copy (STRUCTURE UNCOPYABLE-PROCEDURE) ...)'
          Specifies that the given procedures may not be integrated.

     '(shadow ((PROC-STRUCTURE PROCEDURE) (VAR-STRUCTURE VARIABLE-TO-SHADOW) ...) ...)'
          Specifies that, in PROCEDURE from PROC-STRUCTURE, the global
          variables VARIABLE-TO-SHADOW from their respective
          VAR-STRUCTUREs should be shadowed with local variables, which
          are more likely to be kept in registers for faster operation
          on them.

     '(integrate (CLIENT-PROCEDURE INTEGRABLE-PROCEDURE) ...)'
          Forces INTEGRABLE-PROCEDURE to be integrated in
          CLIENT-PROCEDURE.

          *Note:* The 'integrate' command operates on the global
          program, not on one particular module; each CLIENT-PROCEDURE
          and INTEGRABLE-PROCEDURE is chosen from all variables defined
          in the entirety of the program, across all modules.  It is
          advised that there be only one of each.

     '(header HEADER-LINE ...)'
          Each HEADER-LINE is added to the top of the generated C file,
          after a cpp inclusion of '<stdio.h>' and '"prescheme.h"'.

     The command arguments to 'prescheme-compiler' are optional; they
     are used only to optimize the compiled program at the programmer's
     request.


File: scheme48.info,  Node: Example Pre-Scheme compiler usage,  Next: Running Pre-Scheme as Scheme,  Prev: Invoking the Pre-Scheme compiler,  Up: Pre-Scheme

9.6 Example Pre-Scheme compiler usage
=====================================

The 'ps-compiler/compile-vm.scm', 'ps-compiler/compile-gc.scm', and
'ps-compiler/compile-vm-no-gc.scm' files give examples of running the
Pre-Scheme compiler.  They are Scheme48 command programs (*note Command
programs::), to be loaded into the 'exec' package after having already
loaded the Pre-Scheme compiler.  'compile-vm.scm' &
'compile-vm-no-gc.scm' generate a new 'scheme48vm.c' in the 'scheme/vm/'
directory -- 'compile-vm.scm' includes the garbage collector, while
'compile-vm-no-gc.scm' does not (1) --, and 'compile-gc.scm' generates a
new 'scheme48heap.c', 'scheme48read-image.c', & 'scheme48write-image.c'
in the 'scheme/vm/' directory.

   Here is a somewhat simpler example.  It assumes a pre-built image
with the Pre-Scheme compiler loaded is in the 'ps-compiler.image' file
in the current directory (*note Invoking the Pre-Scheme compiler::,
where there is a description of how to dump an image with the Pre-Scheme
compiler loaded).

     % ls
     hello.scm               packages.scm            ps-compiler.image
     % cat hello.scm
     (define (main argc argv)
       (if (= argc 2)
           (let ((out (current-output-port)))
             (write-string "Hello, world, " out)
             (write-string (vector-ref argv 1) out)
             (write-char #\! out)
             (newline out)
             0)
           (let ((out (current-error-port)))
             (write-string "Usage: " out)
             (write-string (vector-ref argv 0) out)
             (write-string " <user>" out)
             (newline out)
             (write-string "  Greets the world & <user>." out)
             (newline out)
             -1)))
     % cat packages.scm
     (define-structure hello (export main)
       (open prescheme)
       (files hello))
     % scheme48 -i ps-compiler.image
     heap size 3000000 is too small, using 4770088
     Welcome to Scheme 48 1.3 (Pre-Scheme)
     Copyright (c) 1993-2005 by Richard Kelsey and Jonathan Rees.
     Please report bugs to scheme-48-bugs@s48.org.
     Get more information at http://www.s48.org/.
     Type ,? (comma question-mark) for help.
     > (prescheme-compiler 'hello '("packages.scm") 'hello-init "hello.c")
     packages.scm
      hello.scmChecking types
      main : ((integer **char) -> integer)
     In-lining single-use procedures
     Call Graph:
     <procedure name>
       <called non-tail-recursively>
       <called tail-recursively>
     main  (exported)
     Merging forms
     Translating
      main
     #{Unspecific}
     > ,exit
     % cat hello.c
     #include <stdio.h>
     #include "prescheme.h"

     long main(long, char**);


     long main(long argc_0X, char **argv_1X)
     {
       FILE * out_3X;
       FILE * out_2X;
      {  if ((1 == argc_0X)) {
         out_2X = stdout;
         ps_write_string("Hello, world, ", out_2X);
         ps_write_string((*(argv_1X + 1)), out_2X);
         { long ignoreXX;
         PS_WRITE_CHAR(33, out_2X, ignoreXX) }
         { long ignoreXX;
         PS_WRITE_CHAR(10, out_2X, ignoreXX) }
         return 0;}
       else {
         out_3X = stderr;
         ps_write_string("Usage: ", out_3X);
         ps_write_string((*(argv_1X + 0)), out_3X);
         ps_write_string(" <user>", out_3X);
         { long ignoreXX;
         PS_WRITE_CHAR(10, out_3X, ignoreXX) }
         ps_write_string("  Greets the world & <user>.", out_3X);
         { long ignoreXX;
         PS_WRITE_CHAR(10, out_3X, ignoreXX) }
         return -1;}}
     }
     %

   ---------- Footnotes ----------

   (1) The actual distribution of Scheme48 separates the garbage
collector and the main virtual machine.


File: scheme48.info,  Node: Running Pre-Scheme as Scheme,  Prev: Example Pre-Scheme compiler usage,  Up: Pre-Scheme

9.7 Running Pre-Scheme as Scheme
================================

To facilitate the operation of Pre-Scheme systems within a high-level
Scheme development environment, Scheme48 simply defines the 'prescheme',
'ps-memory', 'ps-record-types', 'ps-flonums', and 'ps-receive'
structures in terms of Scheme; Pre-Scheme structures can be loaded as
regular Scheme structures because of this.  Those structures and the
interfaces they implement are defined in the files
'scheme/prescheme/interface.scm' and 'scheme/prescheme/package-defs.scm'
from the main Scheme48 distribution; simply load these files into the
config package (*note Module commands::) before loading any Pre-Scheme
configuration files.

   The Pre-Scheme emulation layer in Scheme has some shortcomings:

   * No more than sixteen megabytes can be allocated at once.

   * More than thirty-two or sixty-four or so allocations result in
     addresses overflowing bignums, which deallocations does not affect.

   * Flonum memory access is unimplemented.  (Flonum arithmetic works,
     though.)

   * The layer is very slow.


File: scheme48.info,  Node: References,  Next: Concept index,  Prev: Pre-Scheme,  Up: Top

References
**********

[Cejtin et al. 95]
     Henry Cejtin, Suresh Jagannathan, and Richard Kelsey.  Higher-Order
     Distributed Objects.  In 'ACM Transactions on Programming Languages
     and Systems', vol.  17, pp.  704-739, ACM Press, September 1995.

[Clinger 91]
     William D. Clinger.  Hygienic Macros through Explicit Renaming.  In
     'Lisp Pointers', IV(4): 25-28, December 1991.

[Donald 92]
     Bruce Donald and Jonathan A. Rees.  Program Mobile Robots in
     Scheme!  In 'Proceedings of the 1992 IEEE International Conference
     on Robotics and Automation', 2681-2688.

[Friedman 00]
     Daniel Friedman and Erik Hilsdale.  'Writing Macros in
     Continuation-Passing Style'.  Worksop on Scheme and Functional
     Programming, September 2000.

[Kelsey 89]
     Richard Kelsey.  'Compilation by Program Transformation'.  PhD
     thesis, Yale University, 1989.

[Kelsey 97]
     Richard Kelsey.  'Pre-Scheme: A Scheme Dialect for Systems
     Programming'.  June 1997.

[Museme]
     Franklyn Turbak and Dan Winship.  'Museme: a multi-user simulation
     environment for Scheme'.
     <http://www.bloodandcoffee.net/campbell/code/museme.tar.gz>

[Rees 96]
     Jonathan A. Rees.  'A Security Kernel based on the
     Lambda-Calculus'.  PhD thesis, AI Memo 1564, Massachusetts
     Institute of Technology, Artificial Intelligence Laboratory, 1996.

[Reppy 99]
     John Reppy.  'Concurrent Programming in ML'. Cambridge University
     Press, 1999.

[Shivers 94]
     Olin Shivers.  'A Scheme Shell'.  Tech Report 635, Massachusetts
     Institute of Technology, Laboratory for Computer Science, 1994.

[Shivers 96]
     Olin Shivers.  'A Universal Scripting Framework, or Lambda: the
     Ultimate "Little Language"'.  'Concurrency and Parallelism,
     Programming, Networking, and Security', pp.  254-265, 1996, Joxan
     Jaffar and Roland H. C. Yap (eds).

[Shivers et al. 04]
     Olin Shivers, Brian D. Carlstrom, Martin Gasbichler, and Michael
     Sperber.  'Scsh Reference Manual', for scsh release 0.6.6
     <http://www.scsh.net/docu/docu.html>

[SRFI 1]
     Olin Shivers.  'SRFI 1: List Library' Scheme Requests for
     Implementation, 1999.
     <http://srfi.schemers.org/srfi-1/>

[SRFI 7]
     Richard Kelsey.  'SRFI 7: Feature-Based Program Configuration
     Language' Scheme Requests for Implementation, 1999.
     <http://srfi.schemers.org/srfi-7/>

[SRFI 9]
     Richard Kelsey.  'SRFI 9: Defining Record Types' Scheme Requests
     for Implementation, 1999.
     <http://srfi.schemers.org/srfi-9/>

[SRFI 22]
     Martin Gasbichler and Michael Sperber 'SRFI 22: Running Scheme
     Scripts on Unix' Scheme Requests for Implementation, 2002.
     <http://srfi.schemers.org/srfi-22/>

[SRFI 34]
     Richard Kelsey and Michael Sperber.  'SRFI 34: Exception Handling
     for Programs'.  Scheme Requests for Implementation, 2002.
     <http://srfi.schemers.org/srfi-34/>

[SRFI 35]
     Richard Kelsey and Michael Sperber.  'SRFI 35: Conditions'.  Scheme
     Requests for Implementation, 2002.
     <http://srfi.schemers.org/srfi-35/>


File: scheme48.info,  Node: Concept index,  Next: Binding index,  Prev: References,  Up: Top

Concept index
*************

[index]
* Menu:

* =scheme48/:                            Filenames.           (line 114)
* abstract data types:                   Records.             (line   6)
* accessing file ports' channels:        Channel ports.       (line  43)
* accessing structures:                  Module configuration language.
                                                              (line  23)
* amb operator:                          Library utilities.   (line  83)
* anonymous structures:                  Module configuration language.
                                                              (line 131)
* arrays:                                Library data structures.
                                                              (line  11)
* asynchronous channels:                 Rendezvous communication channels.
                                                              (line  46)
* asynchronous thread communication channels: Higher-level synchronization.
                                                              (line  85)
* atomic regions:                        Optimistic concurrency.
                                                              (line  40)
* auto-integrate optimizer:              Module configuration language.
                                                              (line  67)
* backtrace:                             Debugging commands.  (line  60)
* backtracking:                          Library utilities.   (line  83)
* batch mode:                            Running Scheme48.    (line  56)
* batch mode <1>:                        Command processor switches.
                                                              (line  26)
* binary data operation:                 Bitwise manipulation.
                                                              (line   6)
* binary search trees:                   Library data structures.
                                                              (line  54)
* binding multiple values:               Library utilities.   (line 213)
* bitwise integer operations:            Bitwise manipulation.
                                                              (line   6)
* block input and output:                Ports.               (line  39)
* blocking I/O:                          POSIX file system access.
                                                              (line 115)
* buffered input and output:             Buffered ports & handlers.
                                                              (line   6)
* buffered output forcing:               Miscellaneous features.
                                                              (line  36)
* buffered output forcing <1>:           Ports.               (line  63)
* byte manipulation:                     Bitwise manipulation.
                                                              (line   6)
* C access to Scheme byte vectors:       Accessing Scheme data from C.
                                                              (line 127)
* C access to Scheme fixnums:            Accessing Scheme data from C.
                                                              (line  86)
* C access to Scheme pairs:              Accessing Scheme data from C.
                                                              (line 107)
* C access to Scheme strings:            Accessing Scheme data from C.
                                                              (line 120)
* C access to Scheme vectors:            Accessing Scheme data from C.
                                                              (line 114)
* C and Scheme data conversion:          Accessing Scheme data from C.
                                                              (line  31)
* C dynamic loading:                     Dynamic loading of C modules.
                                                              (line   6)
* C macros for Scheme constants:         Accessing Scheme data from C.
                                                              (line  13)
* C macros on Scheme booleans:           Accessing Scheme data from C.
                                                              (line  80)
* C naming conventions:                  C interface.         (line  64)
* C predicates for Scheme data:          Accessing Scheme data from C.
                                                              (line 100)
* C shared objects:                      Dynamic loading of C modules.
                                                              (line   6)
* callbacks from C and continuations:    Calling Scheme procedures from C.
                                                              (line  14)
* callbacks from C and threads:          Calling Scheme procedures from C.
                                                              (line  14)
* channel utilities, higher-level:       Channels.            (line 108)
* channels:                              Channels.            (line   6)
* channels <1>:                          Rendezvous communication channels.
                                                              (line   9)
* channels <2>:                          Rendezvous communication channels.
                                                              (line  46)
* character sink output ports:           I/O extensions.      (line  25)
* character source input ports:          I/O extensions.      (line  25)
* closing channels:                      Channels.            (line  42)
* closure flattening:                    Module configuration language.
                                                              (line  67)
* closures in Pre-Scheme:                Differences between Pre-Scheme & Scheme.
                                                              (line  18)
* code reloading:                        Using the module system.
                                                              (line  66)
* code reloading <1>:                    Module commands.     (line  29)
* command levels:                        Command processor switches.
                                                              (line  41)
* command levels <1>:                    Command levels.      (line   6)
* command processor help:                Basic commands.      (line   9)
* command processor settings:            Command processor switches.
                                                              (line   6)
* committing proposals:                  Optimistic concurrency.
                                                              (line 278)
* compile-time evaluation in Pre-Scheme: Differences between Pre-Scheme & Scheme.
                                                              (line  60)
* compiler optimization:                 Module configuration language.
                                                              (line  51)
* compound interfaces:                   Module system architecture.
                                                              (line  61)
* compound interfaces <1>:               Module configuration language.
                                                              (line 127)
* condition handlers:                    Condition system.    (line  39)
* condition messages:                    Condition system.    (line  91)
* condition restarting:                  Debugging commands.  (line  69)
* condition types:                       Condition system.    (line  39)
* condition types <1>:                   Condition system.    (line 166)
* conditions:                            Condition system.    (line  39)
* conditions <1>:                        Condition system.    (line 166)
* config package:                        Module commands.     (line  36)
* configuration language:                Module system architecture.
                                                              (line   6)
* configuration language <1>:            Module configuration language.
                                                              (line   6)
* configuration language macros:         Module configuration language.
                                                              (line 205)
* configuring the command processor:     Command processor switches.
                                                              (line   6)
* continuation previews:                 Debugging commands.  (line  60)
* continuations and callbacks from C:    Calling Scheme procedures from C.
                                                              (line  14)
* continuations in Pre-Scheme:           Differences between Pre-Scheme & Scheme.
                                                              (line  48)
* creating directories:                  POSIX file system access.
                                                              (line 127)
* creating POSIX FIFOs:                  POSIX file system access.
                                                              (line 127)
* creating POSIX links:                  POSIX file system access.
                                                              (line 127)
* customized writer:                     Writer.              (line  26)
* customized writer <1>:                 Writer.              (line  58)
* debug data storage control:            Resource statistics and control.
                                                              (line  21)
* defining record types:                 Records.             (line  10)
* deleting directories:                  POSIX file system access.
                                                              (line 136)
* deleting files:                        POSIX file system access.
                                                              (line 136)
* destructuring S-expressions:           Library utilities.   (line  12)
* directory creation:                    POSIX file system access.
                                                              (line 127)
* directory deletion:                    POSIX file system access.
                                                              (line 136)
* directory listing:                     POSIX file system access.
                                                              (line  26)
* directory streams:                     POSIX file system access.
                                                              (line  10)
* disabling command levels:              Command processor switches.
                                                              (line  41)
* disabling command levels <1>:          Command levels.      (line  17)
* disassembly:                           Debugging commands.  (line  21)
* displaying conditions:                 Condition system.    (line 215)
* displaying heap usage:                 Resource statistics and control.
                                                              (line  60)
* dumping heap images:                   Image-building commands.
                                                              (line   6)
* dumping heap images <1>:               Suspending and resuming heap images.
                                                              (line   6)
* dumping Scheme heap images with C data: Interacting with the Scheme heap in C.
                                                              (line  64)
* dynamic bindings:                      Fluid/dynamic bindings.
                                                              (line   6)
* environment flattening:                Module configuration language.
                                                              (line  67)
* environment variables:                 POSIX process environment.
                                                              (line  30)
* error messages:                        Condition system.    (line  91)
* errors:                                Condition system.    (line  39)
* evaluation of top-level code in Pre-Scheme: Differences between Pre-Scheme & Scheme.
                                                              (line  60)
* event:                                 Concurrent ML.       (line   6)
* exceptions:                            Condition system.    (line  39)
* exec language:                         Command programs.    (line   6)
* exec package:                          Command programs.    (line   6)
* executing processes:                   POSIX processes.     (line  44)
* execution timing:                      Resource statistics and control.
                                                              (line  14)
* exiting processes:                     POSIX processes.     (line  40)
* exiting Scheme:                        Basic commands.      (line  18)
* expanding macros:                      Debugging commands.  (line  21)
* exporting bindings from C to Scheme:   Shared bindings between Scheme and C.
                                                              (line  89)
* exporting bindings from Scheme to C:   Shared bindings between Scheme and C.
                                                              (line  44)
* exporting C functions to Scheme:       Shared bindings between Scheme and C.
                                                              (line  94)
* fcntl:                                 POSIX I/O utilities. (line  71)
* fd-port dup'ing:                       POSIX I/O utilities. (line  52)
* fd-port I/O flags:                     POSIX I/O utilities. (line  71)
* fd-ports:                              POSIX I/O utilities. (line  13)
* FIFOs:                                 Queues.              (line   6)
* file access probing:                   POSIX file system access.
                                                              (line 145)
* file channels:                         Channels.            (line  34)
* file deletion:                         POSIX file system access.
                                                              (line 136)
* file descriptor ports:                 POSIX I/O utilities. (line  13)
* file descriptor reassignment:          POSIX I/O utilities. (line  31)
* file info:                             POSIX file system access.
                                                              (line 154)
* file permissions:                      POSIX file system access.
                                                              (line 210)
* filename translations:                 Filenames.           (line  83)
* flat closures:                         Module configuration language.
                                                              (line  67)
* flat environments:                     Module configuration language.
                                                              (line  67)
* flat-environments optimizer:           Module configuration language.
                                                              (line  67)
* fluid bindings:                        Fluid/dynamic bindings.
                                                              (line   6)
* flushing output buffers:               Miscellaneous features.
                                                              (line  36)
* flushing output buffers <1>:           Ports.               (line  63)
* for-syntax:                            Macros in concert with modules.
                                                              (line  56)
* for-syntax <1>:                        Macros in concert with modules.
                                                              (line  77)
* forcing buffered output:               Miscellaneous features.
                                                              (line  36)
* forcing buffered output <1>:           Ports.               (line  63)
* forcing garbage collection:            Resource statistics and control.
                                                              (line  10)
* forking:                               POSIX processes.     (line  10)
* functors:                              Module system architecture.
                                                              (line  71)
* garbage collection in Pre-Scheme:      Differences between Pre-Scheme & Scheme.
                                                              (line  10)
* garbage collection, forcing:           Resource statistics and control.
                                                              (line  10)
* GC protection in C:                    Interacting with the Scheme heap in C.
                                                              (line   6)
* generic functions:                     Generic dispatch system.
                                                              (line   6)
* generic modules:                       Module system architecture.
                                                              (line  71)
* generic predicate dispatch:            Generic dispatch system.
                                                              (line   6)
* graph algorithms:                      Library utilities.   (line  64)
* group ids:                             POSIX process environment.
                                                              (line  14)
* group ids <1>:                         POSIX users and groups.
                                                              (line   6)
* growing vectors:                       Library data structures.
                                                              (line 103)
* heap image dumping:                    Image-building commands.
                                                              (line   6)
* heap image dumping <1>:                Suspending and resuming heap images.
                                                              (line   6)
* heap image resumption:                 Running Scheme48.    (line   6)
* heap image resumption <1>:             Suspending and resuming heap images.
                                                              (line  41)
* heap image writing:                    Image-building commands.
                                                              (line   6)
* heap image writing <1>:                Suspending and resuming heap images.
                                                              (line   6)
* heap size:                             Running Scheme48.    (line  19)
* heap space analysis:                   Resource statistics and control.
                                                              (line  60)
* heap traversal:                        Resource statistics and control.
                                                              (line  83)
* help:                                  Basic commands.      (line   9)
* higher-level channel utilities:        Channels.            (line 108)
* higher-order modules:                  Module system architecture.
                                                              (line  71)
* hygiene of macros in modules:          Macros in concert with modules.
                                                              (line  14)
* I/O flags:                             POSIX I/O utilities. (line  71)
* image dumping:                         Image-building commands.
                                                              (line   6)
* image dumping <1>:                     Suspending and resuming heap images.
                                                              (line   6)
* image writing:                         Image-building commands.
                                                              (line   6)
* image writing <1>:                     Suspending and resuming heap images.
                                                              (line   6)
* immutability:                          Miscellaneous features.
                                                              (line   9)
* importing bindings into C from Scheme: Shared bindings between Scheme and C.
                                                              (line  85)
* importing bindings into Scheme from C: Shared bindings between Scheme and C.
                                                              (line  33)
* importing C functions to Scheme:       Calling C functions from Scheme.
                                                              (line   6)
* importing C functions to Scheme <1>:   Calling C functions from Scheme.
                                                              (line  34)
* in-line procedures:                    Module configuration language.
                                                              (line  67)
* input and output of blocks:            Ports.               (line  39)
* input ports from strings:              I/O extensions.      (line  38)
* installing condition handlers:         Condition system.    (line 125)
* installing proposals:                  Optimistic concurrency.
                                                              (line 288)
* integrated procedures:                 Module configuration language.
                                                              (line  67)
* interaction between continuations and C: Calling Scheme procedures from C.
                                                              (line  14)
* interface abstraction:                 Module system architecture.
                                                              (line  61)
* interface definition forms:            Module configuration language.
                                                              (line  98)
* interface reüse:                       Module system architecture.
                                                              (line  61)
* interfaces:                            Using the module system.
                                                              (line 126)
* interfaces <1>:                        Module system architecture.
                                                              (line  14)
* join types:                            Static type system.  (line  87)
* limiting output:                       I/O extensions.      (line  53)
* line- & column-tracking ports:         I/O extensions.      (line   8)
* listing directories:                   POSIX file system access.
                                                              (line  26)
* locks for mutual exclusion:            Pessimistic concurrency.
                                                              (line   6)
* logging operations:                    Port data type.      (line  83)
* logging operations <1>:                Optimistic concurrency.
                                                              (line 100)
* logs:                                  Optimistic concurrency.
                                                              (line  25)
* loopholes in the type system:          Type annotations.    (line   6)
* low-level access to records:           Records.             (line 216)
* low-level macros:                      Explicit renaming macros.
                                                              (line   6)
* macro expansion:                       Debugging commands.  (line  21)
* macro hygiene in modules:              Macros in concert with modules.
                                                              (line  14)
* macro referential transparency in modules: Macros in concert with modules.
                                                              (line  14)
* macros in the module configuration language: Module configuration language.
                                                              (line 205)
* macros, low-level:                     Explicit renaming macros.
                                                              (line   6)
* macros, unhygienic:                    Explicit renaming macros.
                                                              (line   6)
* making directories:                    POSIX file system access.
                                                              (line 127)
* marshalling:                           Library utilities.   (line 257)
* meet types:                            Static type system.  (line  87)
* memory management in Pre-Scheme:       Differences between Pre-Scheme & Scheme.
                                                              (line  10)
* memory management in Pre-Scheme <1>:   Compound Pre-Scheme data manipulation.
                                                              (line   6)
* memory management in Pre-Scheme <2>:   Low-level Pre-Scheme memory manipulation.
                                                              (line   6)
* memory size:                           Running Scheme48.    (line  19)
* message-passing:                       Rendezvous communication channels.
                                                              (line   9)
* message-passing <1>:                   Rendezvous communication channels.
                                                              (line  46)
* modified interfaces:                   Module configuration language.
                                                              (line 142)
* modified structures:                   Module configuration language.
                                                              (line 142)
* module language:                       Module system architecture.
                                                              (line   6)
* module language <1>:                   Module configuration language.
                                                              (line   6)
* module language macros:                Module configuration language.
                                                              (line 205)
* modules:                               Module system architecture.
                                                              (line  14)
* multimethod dispatch:                  Generic dispatch system.
                                                              (line   6)
* multiple value binding:                Library utilities.   (line 213)
* mutability:                            Miscellaneous features.
                                                              (line   9)
* mutex locks:                           Pessimistic concurrency.
                                                              (line   6)
* mutual exclusion:                      Pessimistic concurrency.
                                                              (line   6)
* namelists:                             Filenames.           (line  36)
* networking:                            TCP & UDP sockets.   (line   6)
* noise output:                          Miscellaneous features.
                                                              (line  42)
* noise output <1>:                      Ports.               (line  96)
* nonblocking I/O:                       POSIX file system access.
                                                              (line 115)
* nondeterminism:                        Library utilities.   (line  83)
* numbers in Pre-Scheme:                 Differences between Pre-Scheme & Scheme.
                                                              (line  54)
* object dumping:                        Library utilities.   (line 257)
* object reference analysis:             Resource statistics and control.
                                                              (line  83)
* opaque data types:                     Records.             (line   6)
* opening structures:                    Module commands.     (line  17)
* opening structures <1>:                Module system architecture.
                                                              (line  31)
* opening structures <2>:                Module configuration language.
                                                              (line  23)
* optimistic concurrency logging operations: Port data type.  (line  83)
* optimistic concurrency logging operations <1>: Optimistic concurrency.
                                                              (line 100)
* optimistic concurrency logs:           Optimistic concurrency.
                                                              (line  25)
* optimistic concurrency proposals:      Optimistic concurrency.
                                                              (line  25)
* optimistically concurrent record types: Optimistic concurrency.
                                                              (line 129)
* optimizer:                             Module configuration language.
                                                              (line  51)
* output port buffer forcing:            Miscellaneous features.
                                                              (line  36)
* output port buffer forcing <1>:        Ports.               (line  63)
* output ports to strings:               I/O extensions.      (line  38)
* package clauses:                       Module configuration language.
                                                              (line  18)
* packages:                              Module system architecture.
                                                              (line  14)
* parameterized modules:                 Module system architecture.
                                                              (line  71)
* parametric polymorphism:               Static type system.  (line  84)
* phase separation:                      Macros in concert with modules.
                                                              (line  19)
* pipe I/O:                              POSIX I/O utilities. (line   9)
* port to channel conversion:            Channel ports.       (line  43)
* ports that track line & column numbers: I/O extensions.     (line   8)
* ports with line & column numbers:      I/O extensions.      (line   8)
* POSIX directory access:                POSIX file system access.
                                                              (line  10)
* POSIX environment variables:           POSIX process environment.
                                                              (line  30)
* POSIX exec:                            POSIX processes.     (line  44)
* POSIX fcntl:                           POSIX I/O utilities. (line  71)
* POSIX FIFOs:                           POSIX file system access.
                                                              (line 127)
* POSIX file creation masks:             POSIX file system access.
                                                              (line 122)
* POSIX file opening:                    POSIX file system access.
                                                              (line  37)
* POSIX file permissions:                POSIX file system access.
                                                              (line 210)
* POSIX fork:                            POSIX processes.     (line  10)
* POSIX group ids:                       POSIX process environment.
                                                              (line  14)
* POSIX group info:                      POSIX users and groups.
                                                              (line  27)
* POSIX links:                           POSIX file system access.
                                                              (line 127)
* POSIX pipe I/O:                        POSIX I/O utilities. (line   9)
* POSIX process exiting:                 POSIX processes.     (line  40)
* POSIX process ids:                     POSIX processes.     (line  18)
* POSIX process ids <1>:                 POSIX process environment.
                                                              (line   9)
* POSIX process termination:             POSIX processes.     (line  27)
* POSIX terminal ports:                  POSIX I/O utilities. (line  78)
* POSIX user ids:                        POSIX process environment.
                                                              (line  14)
* POSIX user info:                       POSIX users and groups.
                                                              (line  27)
* POSIX working directory:               POSIX file system access.
                                                              (line  32)
* Pre-Scheme closures:                   Differences between Pre-Scheme & Scheme.
                                                              (line  18)
* Pre-Scheme garbage collection:         Differences between Pre-Scheme & Scheme.
                                                              (line  10)
* Pre-Scheme memory management:          Differences between Pre-Scheme & Scheme.
                                                              (line  10)
* Pre-Scheme memory management <1>:      Compound Pre-Scheme data manipulation.
                                                              (line   6)
* Pre-Scheme memory management <2>:      Low-level Pre-Scheme memory manipulation.
                                                              (line   6)
* Pre-Scheme numbers:                    Differences between Pre-Scheme & Scheme.
                                                              (line  54)
* Pre-Scheme strings:                    Compound Pre-Scheme data manipulation.
                                                              (line   6)
* Pre-Scheme tail call optimization:     Differences between Pre-Scheme & Scheme.
                                                              (line  28)
* Pre-Scheme tail call optimization <1>: Tail call optimization in Pre-Scheme.
                                                              (line   6)
* Pre-Scheme top-level evaluation:       Differences between Pre-Scheme & Scheme.
                                                              (line  60)
* Pre-Scheme type inference:             Differences between Pre-Scheme & Scheme.
                                                              (line  42)
* Pre-Scheme type inference <1>:         Pre-Scheme type specifiers.
                                                              (line   6)
* Pre-Scheme vectors:                    Compound Pre-Scheme data manipulation.
                                                              (line   6)
* pretty-printing:                       Library utilities.   (line  29)
* previewing continuations:              Debugging commands.  (line  60)
* printing:                              Library utilities.   (line  29)
* printing conditions:                   Condition system.    (line 215)
* procedure integration:                 Module configuration language.
                                                              (line  67)
* procedures, tracing:                   Debugging commands.  (line  47)
* proceeding from errors:                Debugging commands.  (line  69)
* process forking:                       POSIX processes.     (line  10)
* process ids:                           POSIX processes.     (line  18)
* process ids <1>:                       POSIX process environment.
                                                              (line   9)
* process termination:                   POSIX processes.     (line  27)
* programmatic record types:             Records.             (line 134)
* proposals:                             Optimistic concurrency.
                                                              (line  25)
* proposals <1>:                         Optimistic concurrency.
                                                              (line 268)
* proposals, committing:                 Optimistic concurrency.
                                                              (line 278)
* proposals, installing:                 Optimistic concurrency.
                                                              (line 288)
* quitting Scheme:                       Basic commands.      (line  18)
* real time:                             Library utilities.   (line 283)
* record resumers:                       Interacting with the Scheme heap in C.
                                                              (line  64)
* record types, defining:                Records.             (line  10)
* record types, programmatic:            Records.             (line 134)
* records, low-level access to:          Records.             (line 216)
* referential transparency of macros in modules: Macros in concert with modules.
                                                              (line  14)
* reflective tower:                      Macros in concert with modules.
                                                              (line  56)
* reloading code:                        Using the module system.
                                                              (line  66)
* reloading code <1>:                    Module commands.     (line  29)
* removing directories:                  POSIX file system access.
                                                              (line 136)
* removing files:                        POSIX file system access.
                                                              (line 136)
* renaming files:                        POSIX file system access.
                                                              (line 136)
* rendezvous:                            Concurrent ML.       (line   6)
* resizable vectors:                     Library data structures.
                                                              (line 103)
* restoring C data after resuming images: Interacting with the Scheme heap in C.
                                                              (line  64)
* resuming heap images:                  Running Scheme48.    (line   6)
* resuming heap images <1>:              Suspending and resuming heap images.
                                                              (line  41)
* resuming suspended threads:            Custom thread synchronization.
                                                              (line   6)
* returning from errors:                 Debugging commands.  (line  69)
* run time:                              Library utilities.   (line 283)
* S-expression destructuring:            Library utilities.   (line  12)
* Scheme and C data conversion:          Accessing Scheme data from C.
                                                              (line  31)
* Scheme boolean testing in C:           Accessing Scheme data from C.
                                                              (line  80)
* Scheme byte vector operations in C:    Accessing Scheme data from C.
                                                              (line 127)
* Scheme callbacks in C:                 Calling Scheme procedures from C.
                                                              (line   6)
* Scheme constants in C:                 Accessing Scheme data from C.
                                                              (line  13)
* Scheme data predicates in C:           Accessing Scheme data from C.
                                                              (line 100)
* Scheme fixnums from C:                 Accessing Scheme data from C.
                                                              (line  86)
* Scheme pair operations in C:           Accessing Scheme data from C.
                                                              (line 107)
* Scheme string operations in C:         Accessing Scheme data from C.
                                                              (line 120)
* Scheme vector operations in C:         Accessing Scheme data from C.
                                                              (line 114)
* scheme48.h:                            Accessing Scheme data from C.
                                                              (line   6)
* separate compilation:                  Macros in concert with modules.
                                                              (line  10)
* serialization:                         Library utilities.   (line 257)
* sharing data between Scheme and C:     Shared bindings between Scheme and C.
                                                              (line   6)
* signal queues:                         POSIX signals.       (line 125)
* signalling conditions:                 Condition system.    (line  39)
* simple character sink output ports:    I/O extensions.      (line  25)
* simple character source input ports:   I/O extensions.      (line  25)
* simple interfaces:                     Module configuration language.
                                                              (line 104)
* sleeping threads:                      Basic thread operations.
                                                              (line  16)
* space usage analysis:                  Resource statistics and control.
                                                              (line  60)
* spawning threads:                      Basic thread operations.
                                                              (line   8)
* stack size:                            Running Scheme48.    (line  28)
* static type analysis:                  Static type system.  (line   6)
* static types in Pre-Scheme:            Differences between Pre-Scheme & Scheme.
                                                              (line  42)
* static types in Pre-Scheme <1>:        Pre-Scheme type specifiers.
                                                              (line   6)
* storage control of debug data:         Resource statistics and control.
                                                              (line  21)
* storage leak analysis:                 Resource statistics and control.
                                                              (line  83)
* storing C data in the Scheme heap:     Interacting with the Scheme heap in C.
                                                              (line  46)
* string input ports:                    I/O extensions.      (line  38)
* string matching:                       POSIX regular expressions.
                                                              (line   6)
* string output ports:                   I/O extensions.      (line  38)
* string ports:                          I/O extensions.      (line  38)
* strings in Pre-Scheme:                 Compound Pre-Scheme data manipulation.
                                                              (line   6)
* strongly-connected graph components:   Library utilities.   (line  64)
* structure definition forms:            Module configuration language.
                                                              (line  79)
* structures:                            Module system architecture.
                                                              (line  14)
* structures, accessing:                 Module configuration language.
                                                              (line  23)
* structures, opening:                   Module commands.     (line  17)
* structures, opening <1>:               Module system architecture.
                                                              (line  31)
* structures, opening <2>:               Module configuration language.
                                                              (line  23)
* suspending threads:                    Custom thread synchronization.
                                                              (line   6)
* synchronous channels:                  Rendezvous communication channels.
                                                              (line   9)
* syntactic tower:                       Macros in concert with modules.
                                                              (line  56)
* syntax expansion:                      Debugging commands.  (line  21)
* tail call optimization in Pre-Scheme:  Differences between Pre-Scheme & Scheme.
                                                              (line  28)
* tail call optimization in Pre-Scheme <1>: Tail call optimization in Pre-Scheme.
                                                              (line   6)
* tail recursion in Pre-Scheme:          Differences between Pre-Scheme & Scheme.
                                                              (line  28)
* tail recursion in Pre-Scheme <1>:      Tail call optimization in Pre-Scheme.
                                                              (line   6)
* terminal ports:                        POSIX I/O utilities. (line  78)
* terminating threads:                   Basic thread operations.
                                                              (line  23)
* thread cells:                          Custom thread synchronization.
                                                              (line  11)
* thread communication channels, asynchronous: Higher-level synchronization.
                                                              (line  85)
* thread descriptors:                    Basic thread operations.
                                                              (line  27)
* thread queues:                         Custom thread synchronization.
                                                              (line  11)
* thread sleeping:                       Basic thread operations.
                                                              (line  16)
* thread termination:                    Basic thread operations.
                                                              (line  23)
* thread yielding:                       Basic thread operations.
                                                              (line  16)
* threads and callbacks from C:          Calling Scheme procedures from C.
                                                              (line  14)
* threads, spawning:                     Basic thread operations.
                                                              (line   8)
* time:                                  Rendezvous base combinators.
                                                              (line  59)
* time <1>:                              Library utilities.   (line 283)
* timing execution:                      Resource statistics and control.
                                                              (line  14)
* top-level evaluation in Pre-Scheme:    Differences between Pre-Scheme & Scheme.
                                                              (line  60)
* towers of evaluation phases:           Macros in concert with modules.
                                                              (line  19)
* tracing:                               Debugging commands.  (line  47)
* transaction logs:                      Optimistic concurrency.
                                                              (line  25)
* type dispatch:                         Generic dispatch system.
                                                              (line   6)
* type inference:                        Static type system.  (line   6)
* type lattice:                          Static type system.  (line  54)
* type system loopholes:                 Type annotations.    (line   6)
* undefined imported bindings:           Running Scheme48.    (line  53)
* unhygienic macros:                     Explicit renaming macros.
                                                              (line   6)
* unspecific:                            Various utilities.   (line  12)
* unspecified:                           Various utilities.   (line  12)
* user ids:                              POSIX process environment.
                                                              (line  14)
* user ids <1>:                          POSIX users and groups.
                                                              (line   6)
* user package:                          Module commands.     (line  36)
* usual resumer:                         Suspending and resuming heap images.
                                                              (line  41)
* vectors in Pre-Scheme:                 Compound Pre-Scheme data manipulation.
                                                              (line   6)
* waiting for POSIX processes:           POSIX processes.     (line  27)
* warnings:                              Condition system.    (line  39)
* working directory:                     POSIX file system access.
                                                              (line  32)
* writer, customized:                    Writer.              (line  26)
* writer, customized <1>:                Writer.              (line  58)
* writing heap images:                   Image-building commands.
                                                              (line   6)
* writing heap images <1>:               Suspending and resuming heap images.
                                                              (line   6)
* yielding threads:                      Basic thread operations.
                                                              (line  16)


File: scheme48.info,  Node: Binding index,  Next: Structure index,  Prev: Concept index,  Up: Top

Binding index
*************

[index]
* Menu:

* &disclose-condition:                   Condition system.    (line 229)
* *:                                     Scheme bindings in Pre-Scheme.
                                                              (line  47)
* *load-file-type*:                      Filenames.           (line  10)
* *scheme-file-type*:                    Filenames.           (line   9)
* +:                                     Scheme bindings in Pre-Scheme.
                                                              (line  44)
* ,?:                                    Basic commands.      (line  11)
* ,? <1>:                                Basic commands.      (line  12)
* ,bound?:                               Debugging commands.  (line   9)
* ,build:                                Image-building commands.
                                                              (line  11)
* ,collect:                              Resource statistics and control.
                                                              (line  10)
* ,condition:                            Command levels.      (line  40)
* ,condition <1>:                        Debugging commands.  (line  41)
* ,config:                               Module commands.     (line  38)
* ,config <1>:                           Module commands.     (line  39)
* ,config-package-is:                    Module commands.     (line  70)
* ,debug:                                Debugging commands.  (line  65)
* ,dis:                                  Debugging commands.  (line  23)
* ,dis <1>:                              Debugging commands.  (line  24)
* ,dump:                                 Image-building commands.
                                                              (line  12)
* ,dump <1>:                             Image-building commands.
                                                              (line  13)
* ,end:                                  Emacs integration commands.
                                                              (line  11)
* ,exec:                                 Command programs.    (line  12)
* ,exec <1>:                             Command programs.    (line  13)
* ,exit:                                 Basic commands.      (line  18)
* ,exit <1>:                             Basic commands.      (line  19)
* ,exit-when-done:                       Basic commands.      (line  20)
* ,exit-when-done <1>:                   Basic commands.      (line  21)
* ,expand:                               Debugging commands.  (line  21)
* ,expand <1>:                           Debugging commands.  (line  22)
* ,flush:                                Resource statistics and control.
                                                              (line  23)
* ,flush <1>:                            Resource statistics and control.
                                                              (line  24)
* ,for-syntax:                           Module commands.     (line  40)
* ,for-syntax <1>:                       Module commands.     (line  41)
* ,forget:                               Emacs integration commands.
                                                              (line  22)
* ,from-file:                            Emacs integration commands.
                                                              (line  10)
* ,go:                                   Basic commands.      (line  28)
* ,help:                                 Basic commands.      (line   9)
* ,help <1>:                             Basic commands.      (line  10)
* ,in:                                   Module commands.     (line  43)
* ,in <1>:                               Module commands.     (line  44)
* ,inspect:                              Inspector.           (line  25)
* ,inspect <1>:                          Inspector.           (line  26)
* ,keep:                                 Resource statistics and control.
                                                              (line  21)
* ,keep <1>:                             Resource statistics and control.
                                                              (line  22)
* ,load:                                 Basic commands.      (line  49)
* ,load-package:                         Module commands.     (line  28)
* ,load-srfi-7-program:                  SRFI 7.              (line   9)
* ,load-srfi-7-script:                   SRFI 7.              (line  10)
* ,new-package:                          Module commands.     (line  42)
* ,open:                                 Module commands.     (line  17)
* ,pop:                                  Command levels.      (line  24)
* ,preview:                              Debugging commands.  (line  60)
* ,proceed:                              Debugging commands.  (line  69)
* ,proceed <1>:                          Debugging commands.  (line  70)
* ,push:                                 Command levels.      (line  23)
* ,reload-package:                       Module commands.     (line  29)
* ,reset:                                Command levels.      (line  27)
* ,reset <1>:                            Command levels.      (line  28)
* ,resume:                               Command levels.      (line  25)
* ,resume <1>:                           Command levels.      (line  26)
* ,run:                                  Basic commands.      (line  40)
* ,set:                                  Command processor switches.
                                                              (line   9)
* ,set <1>:                              Command processor switches.
                                                              (line  10)
* ,set <2>:                              Command processor switches.
                                                              (line  12)
* ,structure:                            Module commands.     (line  75)
* ,threads:                              Command levels.      (line  41)
* ,threads <1>:                          Debugging commands.  (line  42)
* ,time:                                 Resource statistics and control.
                                                              (line  14)
* ,trace:                                Debugging commands.  (line  47)
* ,trace <1>:                            Debugging commands.  (line  48)
* ,translate:                            Basic commands.      (line  61)
* ,undefine:                             Basic commands.      (line  46)
* ,unset:                                Command processor switches.
                                                              (line  11)
* ,untrace:                              Debugging commands.  (line  49)
* ,untrace <1>:                          Debugging commands.  (line  50)
* ,user:                                 Module commands.     (line  36)
* ,user <1>:                             Module commands.     (line  37)
* ,user-package-is:                      Module commands.     (line  69)
* ,where:                                Debugging commands.  (line  10)
* ,where <1>:                            Debugging commands.  (line  11)
* -:                                     Scheme bindings in Pre-Scheme.
                                                              (line  45)
* - <1>:                                 Scheme bindings in Pre-Scheme.
                                                              (line  46)
* :record-type:                          Records.             (line 188)
* <:                                     Scheme bindings in Pre-Scheme.
                                                              (line  49)
* <=:                                    Scheme bindings in Pre-Scheme.
                                                              (line  51)
* =:                                     Scheme bindings in Pre-Scheme.
                                                              (line  48)
* >:                                     Scheme bindings in Pre-Scheme.
                                                              (line  50)
* >=:                                    Scheme bindings in Pre-Scheme.
                                                              (line  52)
* abs:                                   Scheme bindings in Pre-Scheme.
                                                              (line  55)
* access:                                Module configuration language.
                                                              (line  24)
* access-mode:                           POSIX file system access.
                                                              (line 147)
* accessible?:                           POSIX file system access.
                                                              (line 145)
* add-finalizer!:                        Calling C functions from Scheme.
                                                              (line  90)
* add-signal-queue-signal!:              POSIX signals.       (line 158)
* add-to-population!:                    Weak references.     (line  28)
* address+:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  61)
* address-:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  62)
* address->integer:                      Low-level Pre-Scheme memory manipulation.
                                                              (line  80)
* address-difference:                    Low-level Pre-Scheme memory manipulation.
                                                              (line  63)
* address<:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  73)
* address<=:                             Low-level Pre-Scheme memory manipulation.
                                                              (line  75)
* address=:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  72)
* address>:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  74)
* address>=:                             Low-level Pre-Scheme memory manipulation.
                                                              (line  76)
* address?:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  42)
* after-time-rv:                         Rendezvous base combinators.
                                                              (line  63)
* alias:                                 Module configuration language.
                                                              (line 158)
* all-values:                            Library utilities.   (line  93)
* allocate-memory:                       Low-level Pre-Scheme memory manipulation.
                                                              (line  17)
* alphabetic:                            POSIX regular expressions.
                                                              (line 125)
* alphanumeric:                          POSIX regular expressions.
                                                              (line 127)
* always-rv:                             Rendezvous base combinators.
                                                              (line  12)
* and:                                   Scheme bindings in Pre-Scheme.
                                                              (line  15)
* any:                                   Various utilities.   (line 103)
* any <1>:                               Library utilities.   (line 154)
* any-match?:                            POSIX regular expressions.
                                                              (line 224)
* any?:                                  Library utilities.   (line 161)
* arithmetic-shift:                      Bitwise manipulation.
                                                              (line  21)
* arithmetic-shift-right:                Pre-Scheme bitwise manipulation.
                                                              (line  15)
* array:                                 Library data structures.
                                                              (line  15)
* array->vector:                         Library data structures.
                                                              (line  38)
* array-ref:                             Library data structures.
                                                              (line  32)
* array-set!:                            Library data structures.
                                                              (line  33)
* array-shape:                           Library data structures.
                                                              (line  29)
* array?:                                Library data structures.
                                                              (line  26)
* ascii->char:                           ASCII character encoding.
                                                              (line   9)
* ascii-limit:                           ASCII character encoding.
                                                              (line  20)
* ascii-range:                           POSIX regular expressions.
                                                              (line  94)
* ascii-ranges:                          POSIX regular expressions.
                                                              (line  95)
* ascii-whitespaces:                     ASCII character encoding.
                                                              (line  21)
* async-channel?:                        Rendezvous communication channels.
                                                              (line  62)
* at-real-time-rv:                       Rendezvous base combinators.
                                                              (line  62)
* atom?:                                 Library utilities.   (line 126)
* atomically:                            Optimistic concurrency.
                                                              (line  65)
* atomically!:                           Optimistic concurrency.
                                                              (line  66)
* attempt-copy-bytes!:                   Optimistic concurrency.
                                                              (line 115)
* begin:                                 Module configuration language.
                                                              (line  46)
* begin <1>:                             Module configuration language.
                                                              (line 195)
* bit-count:                             Bitwise manipulation.
                                                              (line  26)
* bitwise-and:                           Bitwise manipulation.
                                                              (line  15)
* bitwise-and <1>:                       Pre-Scheme bitwise manipulation.
                                                              (line   8)
* bitwise-ior:                           Bitwise manipulation.
                                                              (line  16)
* bitwise-ior <1>:                       Pre-Scheme bitwise manipulation.
                                                              (line   9)
* bitwise-not:                           Bitwise manipulation.
                                                              (line  18)
* bitwise-not <1>:                       Pre-Scheme bitwise manipulation.
                                                              (line  11)
* bitwise-xor:                           Bitwise manipulation.
                                                              (line  17)
* bitwise-xor <1>:                       Pre-Scheme bitwise manipulation.
                                                              (line  10)
* blank:                                 POSIX regular expressions.
                                                              (line 133)
* breakpoint:                            Library utilities.   (line 118)
* byte-vector:                           Bitwise manipulation.
                                                              (line  40)
* byte-vector-length:                    Bitwise manipulation.
                                                              (line  42)
* byte-vector-ref:                       Bitwise manipulation.
                                                              (line  43)
* byte-vector-set!:                      Bitwise manipulation.
                                                              (line  44)
* byte-vector?:                          Bitwise manipulation.
                                                              (line  41)
* call-atomically:                       Optimistic concurrency.
                                                              (line  56)
* call-atomically!:                      Optimistic concurrency.
                                                              (line  57)
* call-ensuring-atomicity:               Optimistic concurrency.
                                                              (line  43)
* call-ensuring-atomicity!:              Optimistic concurrency.
                                                              (line  44)
* call-error:                            Condition system.    (line  82)
* call-error?:                           Condition system.    (line 197)
* call-external:                         Dynamic loading of C modules.
                                                              (line 114)
* call-external-value:                   Calling C functions from Scheme.
                                                              (line  14)
* call-imported-binding:                 Calling C functions from Scheme.
                                                              (line  12)
* call-with-current-input-port:          Ports.               (line 111)
* call-with-current-noise-port:          Ports.               (line 113)
* call-with-current-output-port:         Ports.               (line 112)
* call-with-input-file:                  Channel ports.       (line  10)
* call-with-output-file:                 Channel ports.       (line  11)
* call-with-string-output-port:          I/O extensions.      (line  46)
* call-with-values:                      Scheme bindings in Pre-Scheme.
                                                              (line  39)
* cell-ref:                              Cells.               (line  13)
* cell-set!:                             Cells.               (line  14)
* cell?:                                 Cells.               (line  12)
* channel-abort:                         Channels.            (line  59)
* channel-id:                            Channels.            (line  21)
* channel-maybe-commit-and-close:        Channels.            (line 139)
* channel-maybe-commit-and-read:         Channels.            (line 118)
* channel-maybe-commit-and-write:        Channels.            (line 120)
* channel-maybe-read:                    Channels.            (line  53)
* channel-maybe-write:                   Channels.            (line  56)
* channel-os-index:                      Channels.            (line  23)
* channel-ready?:                        Channels.            (line  46)
* channel-status:                        Channels.            (line  22)
* channel-status-option:                 Channels.            (line  86)
* channel-write:                         Channels.            (line 149)
* channel?:                              Channels.            (line  18)
* channel? <1>:                          Rendezvous communication channels.
                                                              (line  16)
* char->ascii:                           ASCII character encoding.
                                                              (line   8)
* char-pointer->nul-terminated-string:   Low-level Pre-Scheme memory manipulation.
                                                              (line  98)
* char-pointer->string:                  Low-level Pre-Scheme memory manipulation.
                                                              (line  97)
* char-ready?:                           Ports.               (line  31)
* char-sink->output-port:                I/O extensions.      (line  30)
* char-source->input-port:               I/O extensions.      (line  28)
* char<?:                                Scheme bindings in Pre-Scheme.
                                                              (line  37)
* char=?:                                Scheme bindings in Pre-Scheme.
                                                              (line  36)
* check-buffer-timestamp!:               Buffered ports & handlers.
                                                              (line 102)
* choose:                                Rendezvous base combinators.
                                                              (line  30)
* close-all-port:                        POSIX I/O utilities. (line  63)
* close-channel:                         Channels.            (line  42)
* close-directory-stream:                POSIX file system access.
                                                              (line  13)
* close-input-port:                      Ports.               (line  26)
* close-input-port <1>:                  Input & output in Pre-Scheme.
                                                              (line  16)
* close-on-exec?:                        POSIX I/O utilities. (line  66)
* close-output-port:                     Ports.               (line  27)
* close-output-port <1>:                 Input & output in Pre-Scheme.
                                                              (line  17)
* close-socket:                          TCP & UDP sockets.   (line  10)
* code-quote:                            Miscellaneous features.
                                                              (line  93)
* components:                            Integer enumerations.
                                                              (line  22)
* compound-interface:                    Module configuration language.
                                                              (line 127)
* concatenate-symbol:                    Library utilities.   (line 111)
* cond:                                  Scheme bindings in Pre-Scheme.
                                                              (line  17)
* condition-predicate:                   Condition system.    (line 184)
* condition-stuff:                       Condition system.    (line 190)
* condition-type:                        Condition system.    (line 189)
* condvar-has-value?:                    Higher-level synchronization.
                                                              (line  44)
* condvar-value:                         Higher-level synchronization.
                                                              (line  45)
* condvar?:                              Higher-level synchronization.
                                                              (line  24)
* control:                               POSIX regular expressions.
                                                              (line 132)
* copy-array:                            Library data structures.
                                                              (line  16)
* copy-memory!:                          Low-level Pre-Scheme memory manipulation.
                                                              (line  87)
* count%:                                Synchronous sequences.
                                                              (line  23)
* count*:                                Sequence types.      (line   9)
* current-column:                        I/O extensions.      (line  16)
* current-error-port:                    Ports.               (line  81)
* current-input-port:                    Ports.               (line  78)
* current-input-port <1>:                Scheme bindings in Pre-Scheme.
                                                              (line  40)
* current-noise-port:                    Miscellaneous features.
                                                              (line  42)
* current-noise-port <1>:                Ports.               (line  80)
* current-output-port:                   Ports.               (line  79)
* current-output-port <1>:               Scheme bindings in Pre-Scheme.
                                                              (line  41)
* current-proposal:                      Optimistic concurrency.
                                                              (line 269)
* current-row:                           I/O extensions.      (line  15)
* current-thread:                        Basic thread operations.
                                                              (line  30)
* current-time:                          POSIX time.          (line  12)
* d:                                     Inspector.           (line  67)
* deallocate:                            Compound Pre-Scheme data manipulation.
                                                              (line  43)
* deallocate-memory:                     Low-level Pre-Scheme memory manipulation.
                                                              (line  18)
* debug-message:                         Miscellaneous features.
                                                              (line  60)
* def:                                   Module configuration language.
                                                              (line  94)
* default-buffer-size:                   Buffered ports & handlers.
                                                              (line  97)
* default-hash-function:                 Hash tables.         (line  51)
* define:                                Scheme bindings in Pre-Scheme.
                                                              (line  10)
* define <1>:                            Scheme bindings in Pre-Scheme.
                                                              (line  11)
* define-condition-type:                 Condition system.    (line 179)
* define-enum-set-type:                  Enumerated/finite types and sets.
                                                              (line  95)
* define-enumerated-type:                Enumerated/finite types and sets.
                                                              (line  21)
* define-enumeration:                    Integer enumerations.
                                                              (line  14)
* define-exported-binding:               Shared bindings between Scheme and C.
                                                              (line  45)
* define-exported-binding <1>:           Calling C functions from Scheme.
                                                              (line  83)
* define-finite-type:                    Enumerated/finite types and sets.
                                                              (line  53)
* define-generic:                        Generic dispatch system.
                                                              (line  33)
* define-imported-binding:               Shared bindings between Scheme and C.
                                                              (line  34)
* define-indentation:                    Library utilities.   (line  49)
* define-interface:                      Module configuration language.
                                                              (line  98)
* define-method:                         Generic dispatch system.
                                                              (line  43)
* define-module:                         Module configuration language.
                                                              (line  92)
* define-record-discloser:               Records.             (line 167)
* define-record-resumer:                 Records.             (line 173)
* define-record-resumer <1>:             Calling C functions from Scheme.
                                                              (line 106)
* define-record-type:                    Records.             (line  28)
* define-record-type <1>:                Records.             (line  85)
* define-record-type <2>:                Pre-Scheme record types.
                                                              (line  10)
* define-sharp-macro:                    Reader.              (line  18)
* define-simple-type:                    Generic dispatch system.
                                                              (line  26)
* define-structure:                      Module configuration language.
                                                              (line  82)
* define-structures:                     Module configuration language.
                                                              (line  84)
* define-synchronized-record-type:       Optimistic concurrency.
                                                              (line 129)
* define-syntax:                         Module configuration language.
                                                              (line 208)
* define-syntax <1>:                     Explicit renaming macros.
                                                              (line  24)
* define-syntax <2>:                     Scheme bindings in Pre-Scheme.
                                                              (line  23)
* delete:                                Library utilities.   (line 200)
* delete-from-queue!:                    Queues.              (line  36)
* delq:                                  Library utilities.   (line 194)
* delq!:                                 Library utilities.   (line 195)
* dequeue!:                              Queues.              (line  21)
* dequeue-signal!:                       POSIX signals.       (line 135)
* destructure:                           Library utilities.   (line  15)
* directory-stream?:                     POSIX file system access.
                                                              (line  11)
* disclose-port:                         Ports.               (line  60)
* disclose-record:                       Records.             (line 191)
* display:                               Writer.              (line  20)
* display-condition:                     Condition system.    (line 217)
* display-type-name:                     Writer.              (line  35)
* do:                                    Scheme bindings in Pre-Scheme.
                                                              (line  18)
* dump:                                  Library utilities.   (line 267)
* dup:                                   POSIX I/O utilities. (line  52)
* dup-switching-mode:                    POSIX I/O utilities. (line  53)
* dup2:                                  POSIX I/O utilities. (line  54)
* dynamic-load:                          Dynamic loading of C modules.
                                                              (line  79)
* either:                                Library utilities.   (line  91)
* empty-pipe!:                           Higher-level synchronization.
                                                              (line  96)
* empty-pipe?:                           Higher-level synchronization.
                                                              (line  95)
* empty-queue!:                          Queues.              (line  15)
* enqueue!:                              Queues.              (line  20)
* ensure-atomicity:                      Optimistic concurrency.
                                                              (line  63)
* ensure-atomicity!:                     Optimistic concurrency.
                                                              (line  64)
* enum:                                  Integer enumerations.
                                                              (line  21)
* enum-case:                             Integer enumerations.
                                                              (line  46)
* enum-set->list:                        Enumerated/finite types and sets.
                                                              (line 117)
* enum-set-intersection:                 Enumerated/finite types and sets.
                                                              (line 121)
* enum-set-member?:                      Enumerated/finite types and sets.
                                                              (line 118)
* enum-set-negation:                     Enumerated/finite types and sets.
                                                              (line 123)
* enum-set-union:                        Enumerated/finite types and sets.
                                                              (line 120)
* enum-set=?:                            Enumerated/finite types and sets.
                                                              (line 119)
* enumerand->name:                       Integer enumerations.
                                                              (line  32)
* environment-alist:                     POSIX process environment.
                                                              (line  31)
* eof-object:                            Miscellaneous I/O internals.
                                                              (line  34)
* eq?:                                   Scheme bindings in Pre-Scheme.
                                                              (line  35)
* error:                                 Condition system.    (line  78)
* error <1>:                             Library utilities.   (line 116)
* error <2>:                             Pre-Scheme error handling.
                                                              (line  40)
* error-string:                          Pre-Scheme error handling.
                                                              (line  36)
* error?:                                Condition system.    (line 193)
* errors:                                Pre-Scheme error handling.
                                                              (line  10)
* every:                                 Various utilities.   (line 104)
* every?:                                Library utilities.   (line 162)
* exact-match?:                          POSIX regular expressions.
                                                              (line 225)
* exception-arguments:                   Condition system.    (line 206)
* exception-opcode:                      Condition system.    (line 204)
* exception-reason:                      Condition system.    (line 205)
* exception?:                            Condition system.    (line 203)
* exec:                                  POSIX processes.     (line  44)
* exec-file:                             POSIX processes.     (line  47)
* exec-file-with-environment:            POSIX processes.     (line  48)
* exec-with-alias:                       POSIX processes.     (line  64)
* exec-with-environment:                 POSIX processes.     (line  45)
* exit:                                  POSIX processes.     (line  40)
* export:                                Module configuration language.
                                                              (line 104)
* expose:                                Module configuration language.
                                                              (line 156)
* expt:                                  Scheme bindings in Pre-Scheme.
                                                              (line  58)
* external:                              Pre-Scheme access to C functions and macros.
                                                              (line   6)
* external-name:                         Dynamic loading of C modules.
                                                              (line  92)
* external-value:                        Dynamic loading of C modules.
                                                              (line  93)
* external?:                             Dynamic loading of C modules.
                                                              (line  91)
* fail:                                  Library utilities.   (line 102)
* fd-port?:                              POSIX I/O utilities. (line  19)
* file-info-device:                      POSIX file system access.
                                                              (line 172)
* file-info-group:                       POSIX file system access.
                                                              (line 177)
* file-info-inode:                       POSIX file system access.
                                                              (line 173)
* file-info-last-access:                 POSIX file system access.
                                                              (line 179)
* file-info-last-change:                 POSIX file system access.
                                                              (line 181)
* file-info-last-modification:           POSIX file system access.
                                                              (line 180)
* file-info-link-count:                  POSIX file system access.
                                                              (line 174)
* file-info-mode:                        POSIX file system access.
                                                              (line 178)
* file-info-name:                        POSIX file system access.
                                                              (line 171)
* file-info-owner:                       POSIX file system access.
                                                              (line 176)
* file-info-size:                        POSIX file system access.
                                                              (line 175)
* file-info-type:                        POSIX file system access.
                                                              (line 189)
* file-info?:                            POSIX file system access.
                                                              (line 170)
* file-mode:                             POSIX file system access.
                                                              (line 213)
* file-mode+:                            POSIX file system access.
                                                              (line 244)
* file-mode-:                            POSIX file system access.
                                                              (line 245)
* file-mode->integer:                    POSIX file system access.
                                                              (line 259)
* file-mode<=?:                          POSIX file system access.
                                                              (line 247)
* file-mode=?:                           POSIX file system access.
                                                              (line 246)
* file-mode>=?:                          POSIX file system access.
                                                              (line 248)
* file-mode?:                            POSIX file system access.
                                                              (line 214)
* file-name-directory:                   Filenames.           (line  19)
* file-name-nondirectory:                Filenames.           (line  20)
* file-options:                          POSIX file system access.
                                                              (line  51)
* file-options-on?:                      POSIX file system access.
                                                              (line  52)
* file-type:                             POSIX file system access.
                                                              (line 190)
* file-type-name:                        POSIX file system access.
                                                              (line 192)
* file-type?:                            POSIX file system access.
                                                              (line 191)
* files:                                 Module configuration language.
                                                              (line  45)
* filter:                                Various utilities.   (line  83)
* filter <1>:                            Library utilities.   (line 168)
* filter!:                               Library utilities.   (line 169)
* filter-map:                            Library utilities.   (line 174)
* find-undefined-imported-bindings:      Shared bindings between Scheme and C.
                                                              (line  53)
* first:                                 Library utilities.   (line 153)
* fl*:                                   Pre-Scheme floating point operation.
                                                              (line  14)
* fl+:                                   Pre-Scheme floating point operation.
                                                              (line  11)
* fl-:                                   Pre-Scheme floating point operation.
                                                              (line  12)
* fl- <1>:                               Pre-Scheme floating point operation.
                                                              (line  13)
* fl/:                                   Pre-Scheme floating point operation.
                                                              (line  15)
* fl<:                                   Pre-Scheme floating point operation.
                                                              (line  17)
* fl<=:                                  Pre-Scheme floating point operation.
                                                              (line  19)
* fl=:                                   Pre-Scheme floating point operation.
                                                              (line  16)
* fl>:                                   Pre-Scheme floating point operation.
                                                              (line  18)
* fl>=:                                  Pre-Scheme floating point operation.
                                                              (line  20)
* flonum-ref:                            Low-level Pre-Scheme memory manipulation.
                                                              (line  30)
* flonum-set!:                           Low-level Pre-Scheme memory manipulation.
                                                              (line  31)
* fluid:                                 Fluid/dynamic bindings.
                                                              (line  27)
* fluid-cell-ref:                        Fluid/dynamic bindings.
                                                              (line  29)
* fluid-cell-set!:                       Fluid/dynamic bindings.
                                                              (line  30)
* fold:                                  Various utilities.   (line  44)
* fold->2:                               Various utilities.   (line  66)
* fold->3:                               Various utilities.   (line  68)
* for-syntax:                            Module configuration language.
                                                              (line  41)
* force-channel-output-ports!:           Channel ports.       (line  48)
* force-output:                          Miscellaneous features.
                                                              (line  36)
* force-output <1>:                      Ports.               (line  63)
* force-output <2>:                      Input & output in Pre-Scheme.
                                                              (line  53)
* force-output-if-open:                  Miscellaneous I/O internals.
                                                              (line  38)
* fork:                                  POSIX processes.     (line  10)
* fork-and-forget:                       POSIX processes.     (line  11)
* format:                                Common-Lisp-style formatting.
                                                              (line  13)
* fresh-line:                            I/O extensions.      (line  20)
* get-effective-group-id:                POSIX process environment.
                                                              (line  18)
* get-effective-user-id:                 POSIX process environment.
                                                              (line  15)
* get-external:                          Dynamic loading of C modules.
                                                              (line  90)
* get-file-info:                         POSIX file system access.
                                                              (line 160)
* get-file/link-info:                    POSIX file system access.
                                                              (line 161)
* get-group-id:                          POSIX process environment.
                                                              (line  17)
* get-groups:                            POSIX process environment.
                                                              (line  24)
* get-host-name:                         TCP & UDP sockets.   (line  12)
* get-login-name:                        POSIX process environment.
                                                              (line  25)
* get-parent-process-id:                 POSIX process environment.
                                                              (line  10)
* get-port-info:                         POSIX file system access.
                                                              (line 162)
* get-process-id:                        POSIX process environment.
                                                              (line   9)
* get-user-id:                           POSIX process environment.
                                                              (line  14)
* gobble-line:                           Reader.              (line  31)
* goto:                                  Tail call optimization in Pre-Scheme.
                                                              (line   6)
* graphic:                               POSIX regular expressions.
                                                              (line 130)
* group-id->group-info:                  POSIX users and groups.
                                                              (line  29)
* group-id->integer:                     POSIX users and groups.
                                                              (line  18)
* group-id=?:                            POSIX users and groups.
                                                              (line  17)
* group-id?:                             POSIX users and groups.
                                                              (line  16)
* group-info-id:                         POSIX users and groups.
                                                              (line  42)
* group-info-members:                    POSIX users and groups.
                                                              (line  43)
* group-info-name:                       POSIX users and groups.
                                                              (line  41)
* group-info?:                           POSIX users and groups.
                                                              (line  40)
* guard:                                 Rendezvous base combinators.
                                                              (line  16)
* hexdigit:                              POSIX regular expressions.
                                                              (line 137)
* hide:                                  Module configuration language.
                                                              (line 157)
* host-name:                             POSIX host OS and machine identification.
                                                              (line   6)
* i/o-flags:                             POSIX I/O utilities. (line  71)
* identity:                              Library utilities.   (line 133)
* if:                                    Scheme bindings in Pre-Scheme.
                                                              (line  12)
* ignore-case:                           POSIX regular expressions.
                                                              (line 181)
* ignore-errors:                         Condition system.    (line 153)
* immutable?:                            Miscellaneous features.
                                                              (line   9)
* import-definition:                     Calling C functions from Scheme.
                                                              (line  34)
* import-dynamic-externals:              Dynamic loading of C modules.
                                                              (line  13)
* import-lambda-definition:              Calling C functions from Scheme.
                                                              (line  35)
* input%:                                Synchronous sequences.
                                                              (line  24)
* input*:                                Sequence types.      (line  10)
* input-channel+closer->port:            Channel ports.       (line  35)
* input-channel->port:                   Channel ports.       (line  30)
* input-port-option:                     Ports.               (line  86)
* input-port?:                           Ports.               (line  20)
* insert:                                Various utilities.   (line 129)
* integer->address:                      Low-level Pre-Scheme memory manipulation.
                                                              (line  79)
* integer->file-mode:                    POSIX file system access.
                                                              (line 260)
* integer->group-id:                     POSIX users and groups.
                                                              (line  19)
* integer->mask:                         Boxed bitwise-integer masks.
                                                              (line  42)
* integer->process-id:                   POSIX processes.     (line  21)
* integer->signal:                       POSIX signals.       (line  20)
* integer->user-id:                      POSIX users and groups.
                                                              (line  15)
* integrate:                             Module configuration language.
                                                              (line  52)
* interrupt?:                            Condition system.    (line 199)
* intersection:                          POSIX regular expressions.
                                                              (line 109)
* invalidate-current-proposal!:          Optimistic concurrency.
                                                              (line 279)
* iterate:                               Main looping macros. (line   6)
* jar-put!:                              Rendezvous-synchronized cells.
                                                              (line  62)
* jar-take:                              Rendezvous-synchronized cells.
                                                              (line  53)
* jar-take-rv:                           Rendezvous-synchronized cells.
                                                              (line  52)
* jar?:                                  Rendezvous-synchronized cells.
                                                              (line  46)
* join:                                  Static type system.  (line  87)
* last:                                  Various utilities.   (line 123)
* let:                                   Module configuration language.
                                                              (line 196)
* let <1>:                               Scheme bindings in Pre-Scheme.
                                                              (line  13)
* let*:                                  Scheme bindings in Pre-Scheme.
                                                              (line  14)
* let-fluid:                             Fluid/dynamic bindings.
                                                              (line  44)
* let-fluids:                            Fluid/dynamic bindings.
                                                              (line  45)
* let-syntax:                            Scheme bindings in Pre-Scheme.
                                                              (line  24)
* letrec-syntax:                         Scheme bindings in Pre-Scheme.
                                                              (line  25)
* limit-output:                          I/O extensions.      (line  56)
* limited-write:                         Condition system.    (line 234)
* link:                                  POSIX file system access.
                                                              (line 127)
* list%:                                 Synchronous sequences.
                                                              (line  20)
* list*:                                 Sequence types.      (line   6)
* list->mask:                            Boxed bitwise-integer masks.
                                                              (line  43)
* list->queue:                           Queues.              (line  42)
* list-directory:                        POSIX file system access.
                                                              (line  26)
* list-interface:                        Using the module system.
                                                              (line 131)
* load-dynamic-externals:                Dynamic loading of C modules.
                                                              (line  11)
* lock?:                                 Pessimistic concurrency.
                                                              (line  20)
* logical-shift-right:                   Pre-Scheme bitwise manipulation.
                                                              (line  16)
* lookup-all-externals:                  Dynamic loading of C modules.
                                                              (line 106)
* lookup-environment-variable:           POSIX process environment.
                                                              (line  30)
* lookup-exported-binding:               Shared bindings between Scheme and C.
                                                              (line  44)
* lookup-external:                       Dynamic loading of C modules.
                                                              (line 105)
* lookup-imported-binding:               Shared bindings between Scheme and C.
                                                              (line  33)
* lookup-imported-binding <1>:           Calling C functions from Scheme.
                                                              (line  82)
* lookup-udp-address:                    TCP & UDP sockets.   (line  64)
* loophole:                              Type annotations.    (line   9)
* lower-case:                            POSIX regular expressions.
                                                              (line 122)
* lower-case <1>:                        POSIX regular expressions.
                                                              (line 123)
* m:                                     Inspector.           (line  46)
* machine-name:                          POSIX host OS and machine identification.
                                                              (line  10)
* make-array:                            Library data structures.
                                                              (line  14)
* make-async-channel:                    Rendezvous communication channels.
                                                              (line  61)
* make-buffered-input-port:              Buffered ports & handlers.
                                                              (line  16)
* make-buffered-input-port-handler:      Buffered ports & handlers.
                                                              (line  35)
* make-buffered-output-port:             Buffered ports & handlers.
                                                              (line  18)
* make-buffered-output-port-handler:     Buffered ports & handlers.
                                                              (line  73)
* make-byte-vector:                      Bitwise manipulation.
                                                              (line  39)
* make-cell:                             Cells.               (line  11)
* make-channel:                          Rendezvous communication channels.
                                                              (line  15)
* make-condition:                        Condition system.    (line  67)
* make-condvar:                          Higher-level synchronization.
                                                              (line  23)
* make-directory:                        POSIX file system access.
                                                              (line 128)
* make-exception:                        Condition system.    (line 202)
* make-fifo:                             POSIX file system access.
                                                              (line 129)
* make-fluid:                            Fluid/dynamic bindings.
                                                              (line  24)
* make-immutable!:                       Miscellaneous features.
                                                              (line  10)
* make-input-port-closed!:               Miscellaneous I/O internals.
                                                              (line  29)
* make-integer-table:                    Hash tables.         (line  12)
* make-jar:                              Rendezvous-synchronized cells.
                                                              (line  45)
* make-lock:                             Pessimistic concurrency.
                                                              (line  19)
* make-mask-type:                        Boxed bitwise-integer masks.
                                                              (line  18)
* make-null-output-port:                 Ports.               (line  66)
* make-output-port-closed!:              Miscellaneous I/O internals.
                                                              (line  30)
* make-pipe:                             Higher-level synchronization.
                                                              (line  88)
* make-placeholder:                      Higher-level synchronization.
                                                              (line  69)
* make-placeholder <1>:                  Rendezvous-synchronized cells.
                                                              (line  16)
* make-population:                       Weak references.     (line  27)
* make-port:                             Port data type.      (line   9)
* make-port-handler:                     Port handlers.       (line  12)
* make-proposal:                         Optimistic concurrency.
                                                              (line 268)
* make-queue:                            Queues.              (line   9)
* make-record:                           Records.             (line 225)
* make-record-type:                      Records.             (line 139)
* make-regexp:                           POSIX regular expressions.
                                                              (line  21)
* make-search-tree:                      Library data structures.
                                                              (line  60)
* make-shared-array:                     Library data structures.
                                                              (line  41)
* make-signal-queue:                     POSIX signals.       (line 131)
* make-sparse-vector:                    Library data structures.
                                                              (line 107)
* make-string:                           Compound Pre-Scheme data manipulation.
                                                              (line  29)
* make-string-input-port:                I/O extensions.      (line  41)
* make-string-output-port:               I/O extensions.      (line  44)
* make-string-table:                     Hash tables.         (line  10)
* make-symbol-table:                     Hash tables.         (line  11)
* make-table:                            Hash tables.         (line   9)
* make-table-immutable!:                 Hash tables.         (line  46)
* make-table-maker:                      Hash tables.         (line  25)
* make-time:                             POSIX time.          (line  11)
* make-tracking-input-port:              I/O extensions.      (line  10)
* make-tracking-output-port:             I/O extensions.      (line  11)
* make-unbuffered-input-port:            Buffered ports & handlers.
                                                              (line  29)
* make-unbuffered-output-port:           Buffered ports & handlers.
                                                              (line  30)
* make-vector:                           Compound Pre-Scheme data manipulation.
                                                              (line  12)
* make-weak-pointer:                     Weak references.     (line  13)
* mask->integer:                         Boxed bitwise-integer masks.
                                                              (line  52)
* mask->list:                            Boxed bitwise-integer masks.
                                                              (line  53)
* mask-clear:                            Boxed bitwise-integer masks.
                                                              (line  60)
* mask-has-type?:                        Boxed bitwise-integer masks.
                                                              (line  32)
* mask-intersection:                     Boxed bitwise-integer masks.
                                                              (line  67)
* mask-member?:                          Boxed bitwise-integer masks.
                                                              (line  58)
* mask-negate:                           Boxed bitwise-integer masks.
                                                              (line  69)
* mask-set:                              Boxed bitwise-integer masks.
                                                              (line  59)
* mask-subtract:                         Boxed bitwise-integer masks.
                                                              (line  68)
* mask-type:                             Boxed bitwise-integer masks.
                                                              (line  31)
* mask-type?:                            Boxed bitwise-integer masks.
                                                              (line  20)
* mask-union:                            Boxed bitwise-integer masks.
                                                              (line  66)
* mask?:                                 Boxed bitwise-integer masks.
                                                              (line  21)
* match:                                 POSIX regular expressions.
                                                              (line 226)
* match-end:                             POSIX regular expressions.
                                                              (line  62)
* match-start:                           POSIX regular expressions.
                                                              (line  61)
* match-submatches:                      POSIX regular expressions.
                                                              (line  63)
* match?:                                POSIX regular expressions.
                                                              (line  60)
* max:                                   Scheme bindings in Pre-Scheme.
                                                              (line  54)
* maybe-commit:                          Optimistic concurrency.
                                                              (line 278)
* maybe-commit-and-block:                Custom thread synchronization.
                                                              (line  21)
* maybe-commit-and-block-on-queue:       Custom thread synchronization.
                                                              (line  22)
* maybe-commit-and-make-ready:           Custom thread synchronization.
                                                              (line  31)
* maybe-commit-and-set-condvar!:         Higher-level synchronization.
                                                              (line  29)
* maybe-commit-and-wait-for-condvar:     Higher-level synchronization.
                                                              (line  28)
* maybe-dequeue!:                        Queues.              (line  22)
* maybe-dequeue-signal!:                 POSIX signals.       (line 136)
* maybe-dequeue-thread!:                 Custom thread synchronization.
                                                              (line  39)
* maybe-obtain-lock:                     Pessimistic concurrency.
                                                              (line  22)
* meet:                                  Static type system.  (line  88)
* memory-equal?:                         Low-level Pre-Scheme memory manipulation.
                                                              (line  91)
* memq?:                                 Library utilities.   (line 149)
* menu:                                  Inspector.           (line  45)
* min:                                   Scheme bindings in Pre-Scheme.
                                                              (line  53)
* modify:                                Module configuration language.
                                                              (line 144)
* mvlet:                                 Library utilities.   (line 232)
* mvlet*:                                Library utilities.   (line 231)
* n=:                                    Library utilities.   (line 130)
* name->enumerand:                       Integer enumerations.
                                                              (line  34)
* name->group-info:                      POSIX users and groups.
                                                              (line  30)
* name->signal:                          POSIX signals.       (line  19)
* name->user-info:                       POSIX users and groups.
                                                              (line  28)
* namestring:                            Filenames.           (line  58)
* negate:                                POSIX regular expressions.
                                                              (line 107)
* neq?:                                  Library utilities.   (line 129)
* never-rv:                              Rendezvous base combinators.
                                                              (line   8)
* newline:                               Ports.               (line  55)
* newline <1>:                           Input & output in Pre-Scheme.
                                                              (line  42)
* no-op:                                 Library utilities.   (line 134)
* no-submatches:                         POSIX regular expressions.
                                                              (line 215)
* not:                                   Scheme bindings in Pre-Scheme.
                                                              (line  34)
* note:                                  Condition system.    (line  84)
* note-buffer-reuse!:                    Buffered ports & handlers.
                                                              (line 101)
* note?:                                 Condition system.    (line 195)
* null-address:                          Low-level Pre-Scheme memory manipulation.
                                                              (line  49)
* null-address?:                         Low-level Pre-Scheme memory manipulation.
                                                              (line  57)
* null-list?:                            Library utilities.   (line 139)
* null-pointer:                          Compound Pre-Scheme data manipulation.
                                                              (line  48)
* null-pointer?:                         Compound Pre-Scheme data manipulation.
                                                              (line  49)
* numeric:                               POSIX regular expressions.
                                                              (line 126)
* obtain-lock:                           Pessimistic concurrency.
                                                              (line  21)
* on-queue?:                             Queues.              (line  35)
* one-of:                                POSIX regular expressions.
                                                              (line 153)
* one-value:                             Library utilities.   (line  92)
* open:                                  Module configuration language.
                                                              (line  23)
* open-channel:                          Channels.            (line  34)
* open-channels-list:                    Channels.            (line  82)
* open-directory-stream:                 POSIX file system access.
                                                              (line  10)
* open-file:                             POSIX file system access.
                                                              (line  37)
* open-input-file:                       Channel ports.       (line  14)
* open-input-file <1>:                   Input & output in Pre-Scheme.
                                                              (line  14)
* open-input-port-status:                Miscellaneous I/O internals.
                                                              (line  24)
* open-input-port?:                      Miscellaneous I/O internals.
                                                              (line  19)
* open-output-file:                      Channel ports.       (line  15)
* open-output-file <1>:                  Input & output in Pre-Scheme.
                                                              (line  15)
* open-output-port-status:               Miscellaneous I/O internals.
                                                              (line  25)
* open-output-port?:                     Miscellaneous I/O internals.
                                                              (line  20)
* open-pipe:                             POSIX I/O utilities. (line   9)
* open-socket:                           TCP & UDP sockets.   (line  29)
* open-udp-socket:                       TCP & UDP sockets.   (line  49)
* optimize:                              Module configuration language.
                                                              (line  51)
* or:                                    Scheme bindings in Pre-Scheme.
                                                              (line  16)
* os-node-name:                          POSIX host OS and machine identification.
                                                              (line   7)
* os-release-name:                       POSIX host OS and machine identification.
                                                              (line   8)
* os-version-name:                       POSIX host OS and machine identification.
                                                              (line   9)
* output-channel+closer->port:           Channel ports.       (line  37)
* output-channel->port:                  Channel ports.       (line  31)
* output-port-option:                    Ports.               (line  87)
* output-port-ready?:                    Ports.               (line  32)
* output-port?:                          Ports.               (line  21)
* p:                                     Library utilities.   (line  31)
* partition-list:                        Library utilities.   (line 186)
* partition-list!:                       Library utilities.   (line 187)
* peek-char:                             Input & output in Pre-Scheme.
                                                              (line  26)
* periodically-flushed-ports:            Miscellaneous I/O internals.
                                                              (line  43)
* periodically-force-output!:            Miscellaneous I/O internals.
                                                              (line  42)
* pipe-maybe-read!:                      Higher-level synchronization.
                                                              (line 101)
* pipe-maybe-read?!:                     Higher-level synchronization.
                                                              (line 102)
* pipe-maybe-write!:                     Higher-level synchronization.
                                                              (line 114)
* pipe-push!:                            Higher-level synchronization.
                                                              (line 113)
* pipe-read!:                            Higher-level synchronization.
                                                              (line 100)
* pipe-write!:                           Higher-level synchronization.
                                                              (line 112)
* pipe?:                                 Higher-level synchronization.
                                                              (line  89)
* placeholder-set!:                      Higher-level synchronization.
                                                              (line  75)
* placeholder-set! <1>:                  Rendezvous-synchronized cells.
                                                              (line  31)
* placeholder-value:                     Higher-level synchronization.
                                                              (line  74)
* placeholder-value <1>:                 Rendezvous-synchronized cells.
                                                              (line  24)
* placeholder-value-rv:                  Rendezvous-synchronized cells.
                                                              (line  23)
* placeholder?:                          Higher-level synchronization.
                                                              (line  70)
* placeholder? <1>:                      Rendezvous-synchronized cells.
                                                              (line  17)
* pop-search-tree-max!:                  Library data structures.
                                                              (line  87)
* pop-search-tree-min!:                  Library data structures.
                                                              (line  88)
* population->list:                      Weak references.     (line  29)
* port->channel:                         Channel ports.       (line  43)
* port->fd:                              POSIX I/O utilities. (line  20)
* port-buffer:                           Port data type.      (line  17)
* port-data:                             Port data type.      (line  20)
* port-handler:                          Port data type.      (line  16)
* port-index:                            Port data type.      (line  21)
* port-is-a-terminal?:                   POSIX I/O utilities. (line  78)
* port-limit:                            Port data type.      (line  22)
* port-lock:                             Port data type.      (line  18)
* port-pending-eof?:                     Port data type.      (line  23)
* port-status:                           Port data type.      (line  19)
* port-status-options:                   Miscellaneous I/O internals.
                                                              (line  11)
* port-terminal-name:                    POSIX I/O utilities. (line  79)
* position:                              Various utilities.   (line  91)
* posq:                                  Various utilities.   (line  89)
* posv:                                  Various utilities.   (line  90)
* prefix:                                Module configuration language.
                                                              (line 155)
* prescheme-compiler:                    Invoking the Pre-Scheme compiler.
                                                              (line  44)
* pretty-print:                          Library utilities.   (line  32)
* printing:                              POSIX regular expressions.
                                                              (line 131)
* proc:                                  Static type system.  (line 143)
* proc <1>:                              Static type system.  (line 242)
* procedure:                             Static type system.  (line 142)
* procedure <1>:                         Static type system.  (line 241)
* process-id->integer:                   POSIX processes.     (line  20)
* process-id-exit-status:                POSIX processes.     (line  27)
* process-id-terminating-signal:         POSIX processes.     (line  28)
* process-id=?:                          POSIX processes.     (line  19)
* process-id?:                           POSIX processes.     (line  18)
* provisional-byte-vector-ref:           Optimistic concurrency.
                                                              (line 112)
* provisional-byte-vector-set!:          Optimistic concurrency.
                                                              (line 113)
* provisional-car:                       Optimistic concurrency.
                                                              (line 100)
* provisional-cdr:                       Optimistic concurrency.
                                                              (line 101)
* provisional-cell-ref:                  Optimistic concurrency.
                                                              (line 104)
* provisional-cell-set!:                 Optimistic concurrency.
                                                              (line 105)
* provisional-port-data:                 Port data type.      (line  86)
* provisional-port-handler:              Port data type.      (line  83)
* provisional-port-index:                Port data type.      (line  87)
* provisional-port-limit:                Port data type.      (line  88)
* provisional-port-lock:                 Port data type.      (line  84)
* provisional-port-pending-eof?:         Port data type.      (line  89)
* provisional-port-status:               Port data type.      (line  85)
* provisional-set-car!:                  Optimistic concurrency.
                                                              (line 102)
* provisional-set-cdr!:                  Optimistic concurrency.
                                                              (line 103)
* provisional-set-port-data!:            Port data type.      (line  92)
* provisional-set-port-index!:           Port data type.      (line  93)
* provisional-set-port-limit!:           Port data type.      (line  94)
* provisional-set-port-lock!:            Port data type.      (line  90)
* provisional-set-port-pending-eof?!:    Port data type.      (line  95)
* provisional-set-port-status!:          Port data type.      (line  91)
* provisional-string-ref:                Optimistic concurrency.
                                                              (line 109)
* provisional-string-set!:               Optimistic concurrency.
                                                              (line 110)
* provisional-vector-ref:                Optimistic concurrency.
                                                              (line 106)
* provisional-vector-set!:               Optimistic concurrency.
                                                              (line 107)
* punctuation:                           POSIX regular expressions.
                                                              (line 128)
* q:                                     Inspector.           (line  55)
* queue->list:                           Queues.              (line  41)
* queue-empty?:                          Queues.              (line  14)
* queue-head:                            Queues.              (line  23)
* queue-length:                          Queues.              (line  32)
* queue?:                                Queues.              (line  10)
* quotient:                              Scheme bindings in Pre-Scheme.
                                                              (line  56)
* range:                                 POSIX regular expressions.
                                                              (line  92)
* ranges:                                POSIX regular expressions.
                                                              (line  93)
* read:                                  Reader.              (line  11)
* read-block:                            Ports.               (line  39)
* read-block <1>:                        Low-level Pre-Scheme memory manipulation.
                                                              (line 106)
* read-char:                             Input & output in Pre-Scheme.
                                                              (line  25)
* read-directory-stream:                 POSIX file system access.
                                                              (line  12)
* read-error?:                           Condition system.    (line 198)
* read-integer:                          Input & output in Pre-Scheme.
                                                              (line  27)
* reading-error:                         Reader.              (line  27)
* real-time:                             Library utilities.   (line 286)
* receive:                               Module configuration language.
                                                              (line 197)
* receive <1>:                           Rendezvous communication channels.
                                                              (line  33)
* receive <2>:                           Library utilities.   (line 216)
* receive <3>:                           Multiple return values in Pre-Scheme.
                                                              (line  16)
* receive-async:                         Rendezvous communication channels.
                                                              (line  68)
* receive-async-rv:                      Rendezvous communication channels.
                                                              (line  67)
* receive-rv:                            Rendezvous communication channels.
                                                              (line  32)
* record:                                Records.             (line 226)
* record-accessor:                       Records.             (line 153)
* record-constructor:                    Records.             (line 150)
* record-length:                         Records.             (line 228)
* record-modifier:                       Records.             (line 155)
* record-predicate:                      Records.             (line 152)
* record-ref:                            Records.             (line 229)
* record-set!:                           Records.             (line 230)
* record-space:                          Resource statistics and control.
                                                              (line  65)
* record-type:                           Records.             (line 233)
* record-type-field-names:               Records.             (line 147)
* record-type-name:                      Records.             (line 146)
* record-type?:                          Records.             (line 141)
* record?:                               Records.             (line 227)
* recurring-write:                       Writer.              (line  26)
* reduce:                                Various utilities.   (line  21)
* reduce <1>:                            Main looping macros. (line  57)
* regexp-match:                          POSIX regular expressions.
                                                              (line  44)
* regexp-option:                         POSIX regular expressions.
                                                              (line  31)
* regexp?:                               POSIX regular expressions.
                                                              (line  22)
* release-lock:                          Pessimistic concurrency.
                                                              (line  23)
* relinquish-timeslice:                  Basic thread operations.
                                                              (line  16)
* reload-dynamic-externals:              Dynamic loading of C modules.
                                                              (line  35)
* remainder:                             Scheme bindings in Pre-Scheme.
                                                              (line  57)
* remap-file-descriptors!:               POSIX I/O utilities. (line  31)
* remove-current-proposal!:              Optimistic concurrency.
                                                              (line 271)
* remove-directory:                      POSIX file system access.
                                                              (line 137)
* remove-duplicates:                     Library utilities.   (line 180)
* remove-signal-queue-signal!:           POSIX signals.       (line 160)
* rename:                                Module configuration language.
                                                              (line 159)
* rename <1>:                            POSIX file system access.
                                                              (line 138)
* repeat:                                POSIX regular expressions.
                                                              (line 162)
* repeat <1>:                            POSIX regular expressions.
                                                              (line 163)
* repeat <2>:                            POSIX regular expressions.
                                                              (line 164)
* report-errors-as-warnings:             Condition system.    (line 154)
* restore:                               Library utilities.   (line 275)
* reverse!:                              Library utilities.   (line 144)
* reverse-list->string:                  Miscellaneous features.
                                                              (line  50)
* run-scheme:                            Emacs integration.   (line  62)
* run-time:                              Library utilities.   (line 294)
* S48_BYTE_VECTOR_LENGTH:                Accessing Scheme data from C.
                                                              (line 127)
* S48_BYTE_VECTOR_P:                     Accessing Scheme data from C.
                                                              (line 106)
* S48_BYTE_VECTOR_REF:                   Accessing Scheme data from C.
                                                              (line 128)
* S48_BYTE_VECTOR_SET:                   Accessing Scheme data from C.
                                                              (line 129)
* s48_call_scheme:                       Calling Scheme procedures from C.
                                                              (line   6)
* S48_CAR:                               Accessing Scheme data from C.
                                                              (line 107)
* S48_CDR:                               Accessing Scheme data from C.
                                                              (line 108)
* S48_CHAR_P:                            Accessing Scheme data from C.
                                                              (line 101)
* S48_CHECK_BOOLEAN:                     Raising exceptions from C.
                                                              (line  37)
* S48_CHECK_BYTE_VECTOR:                 Raising exceptions from C.
                                                              (line  43)
* S48_CHECK_CHANNEL:                     Raising exceptions from C.
                                                              (line  42)
* S48_CHECK_INTEGER:                     Raising exceptions from C.
                                                              (line  41)
* S48_CHECK_PAIR:                        Raising exceptions from C.
                                                              (line  39)
* S48_CHECK_RECORD:                      Raising exceptions from C.
                                                              (line  44)
* s48_check_record_type:                 Using Scheme records in C.
                                                              (line  19)
* S48_CHECK_SHARED_BINDING:              Raising exceptions from C.
                                                              (line  45)
* S48_CHECK_STRING:                      Raising exceptions from C.
                                                              (line  40)
* S48_CHECK_SYMBOL:                      Raising exceptions from C.
                                                              (line  38)
* s48_cons:                              Accessing Scheme data from C.
                                                              (line 111)
* S48_DECLARE_GC_PROTECT:                Interacting with the Scheme heap in C.
                                                              (line  16)
* s48_define_exported_binding:           Shared bindings between Scheme and C.
                                                              (line  89)
* S48_ENTER_BOOLEAN:                     Accessing Scheme data from C.
                                                              (line  37)
* s48_enter_byte_vector:                 Accessing Scheme data from C.
                                                              (line  40)
* s48_enter_char:                        Accessing Scheme data from C.
                                                              (line  38)
* s48_enter_double:                      Accessing Scheme data from C.
                                                              (line  43)
* s48_enter_fixnum:                      Accessing Scheme data from C.
                                                              (line  88)
* s48_enter_integer:                     Accessing Scheme data from C.
                                                              (line  42)
* s48_enter_string:                      Accessing Scheme data from C.
                                                              (line  39)
* S48_EOF:                               Accessing Scheme data from C.
                                                              (line  17)
* S48_EQ_P:                              Accessing Scheme data from C.
                                                              (line 100)
* S48_EXPORT_FUNCTION:                   Shared bindings between Scheme and C.
                                                              (line  94)
* S48_EXTRACT_BOOLEAN:                   Accessing Scheme data from C.
                                                              (line  31)
* s48_extract_byte_vector:               Accessing Scheme data from C.
                                                              (line  34)
* s48_extract_char:                      Accessing Scheme data from C.
                                                              (line  32)
* s48_extract_double:                    Accessing Scheme data from C.
                                                              (line  36)
* s48_extract_fixnum:                    Accessing Scheme data from C.
                                                              (line  87)
* s48_extract_integer:                   Accessing Scheme data from C.
                                                              (line  35)
* s48_extract_string:                    Accessing Scheme data from C.
                                                              (line  33)
* S48_EXTRACT_VALUE:                     Interacting with the Scheme heap in C.
                                                              (line  51)
* S48_EXTRACT_VALUE_POINTER:             Interacting with the Scheme heap in C.
                                                              (line  52)
* S48_FALSE:                             Accessing Scheme data from C.
                                                              (line  13)
* S48_FALSE_P:                           Accessing Scheme data from C.
                                                              (line  81)
* S48_FIXNUM_P:                          Accessing Scheme data from C.
                                                              (line  86)
* S48_GC_PROTECT_GLOBAL:                 Interacting with the Scheme heap in C.
                                                              (line  36)
* S48_GC_PROTECT_N:                      Interacting with the Scheme heap in C.
                                                              (line  17)
* S48_GC_UNPROTECT:                      Interacting with the Scheme heap in C.
                                                              (line  19)
* S48_GC_UNPROTECT_GLOBAL:               Interacting with the Scheme heap in C.
                                                              (line  37)
* s48_get_imported_binding:              Shared bindings between Scheme and C.
                                                              (line  85)
* s48_length:                            Accessing Scheme data from C.
                                                              (line 113)
* s48_make_byte_vector:                  Accessing Scheme data from C.
                                                              (line 131)
* s48_make_record:                       Using Scheme records in C.
                                                              (line  12)
* s48_make_string:                       Accessing Scheme data from C.
                                                              (line 124)
* S48_MAKE_VALUE:                        Interacting with the Scheme heap in C.
                                                              (line  50)
* s48_make_vector:                       Accessing Scheme data from C.
                                                              (line 118)
* S48_MAX_FIXNUM_VALUE:                  Accessing Scheme data from C.
                                                              (line  18)
* S48_MIN_FIXNUM_VALUE:                  Accessing Scheme data from C.
                                                              (line  19)
* S48_NULL:                              Accessing Scheme data from C.
                                                              (line  15)
* s48_on_load:                           Dynamic loading of C modules.
                                                              (line  43)
* s48_on_reload:                         Dynamic loading of C modules.
                                                              (line  44)
* S48_PAIR_P:                            Accessing Scheme data from C.
                                                              (line 102)
* s48_raise_argument_number_error:       Raising exceptions from C.
                                                              (line  20)
* s48_raise_argument_type_error:         Raising exceptions from C.
                                                              (line  19)
* s48_raise_closed_channel_error:        Raising exceptions from C.
                                                              (line  24)
* s48_raise_os_error:                    Raising exceptions from C.
                                                              (line  25)
* s48_raise_out_of_memory_error:         Raising exceptions from C.
                                                              (line  26)
* s48_raise_range_error:                 Raising exceptions from C.
                                                              (line  22)
* s48_raise_scheme_exception:            Raising exceptions from C.
                                                              (line  11)
* S48_RECORD_P:                          Using Scheme records in C.
                                                              (line  14)
* S48_RECORD_REF:                        Using Scheme records in C.
                                                              (line  16)
* S48_RECORD_SET:                        Using Scheme records in C.
                                                              (line  17)
* S48_RECORD_TYPE:                       Using Scheme records in C.
                                                              (line  15)
* S48_SET_CAR:                           Accessing Scheme data from C.
                                                              (line 109)
* S48_SET_CDR:                           Accessing Scheme data from C.
                                                              (line 110)
* S48_SET_VALUE:                         Interacting with the Scheme heap in C.
                                                              (line  53)
* S48_SHARED_BINDING_CHECK:              Shared bindings between Scheme and C.
                                                              (line  74)
* S48_SHARED_BINDING_IS_IMPORTP:         Shared bindings between Scheme and C.
                                                              (line  65)
* S48_SHARED_BINDING_NAME:               Shared bindings between Scheme and C.
                                                              (line  63)
* S48_SHARED_BINDING_P:                  Shared bindings between Scheme and C.
                                                              (line  62)
* S48_SHARED_BINDING_REF:                Shared bindings between Scheme and C.
                                                              (line  67)
* S48_SHARED_BINDING_SET:                Shared bindings between Scheme and C.
                                                              (line  68)
* S48_STRING_LENGTH:                     Accessing Scheme data from C.
                                                              (line 120)
* S48_STRING_P:                          Accessing Scheme data from C.
                                                              (line 104)
* S48_STRING_REF:                        Accessing Scheme data from C.
                                                              (line 121)
* S48_STRING_SET:                        Accessing Scheme data from C.
                                                              (line 122)
* S48_SYMBOL_P:                          Accessing Scheme data from C.
                                                              (line 105)
* S48_SYMBOL_TO_STRING:                  Accessing Scheme data from C.
                                                              (line 126)
* S48_TRUE:                              Accessing Scheme data from C.
                                                              (line  14)
* S48_TRUE_P:                            Accessing Scheme data from C.
                                                              (line  80)
* S48_UNSAFE_BYTE_VECTOR_LENGTH:         Unsafe C macros.     (line  38)
* S48_UNSAFE_BYTE_VECTOR_REF:            Unsafe C macros.     (line  39)
* S48_UNSAFE_BYTE_VECTOR_SET:            Unsafe C macros.     (line  41)
* S48_UNSAFE_CAR:                        Unsafe C macros.     (line  20)
* S48_UNSAFE_CDR:                        Unsafe C macros.     (line  21)
* S48_UNSAFE_ENTER_FIXNUM:               Unsafe C macros.     (line  18)
* S48_UNSAFE_EXTRACT_CHAR:               Unsafe C macros.     (line  13)
* S48_UNSAFE_EXTRACT_DOUBLE:             Unsafe C macros.     (line  16)
* S48_UNSAFE_EXTRACT_FIXNUM:             Unsafe C macros.     (line  17)
* S48_UNSAFE_EXTRACT_INTEGER:            Unsafe C macros.     (line  15)
* S48_UNSAFE_EXTRACT_STRING:             Unsafe C macros.     (line  14)
* S48_UNSAFE_EXTRACT_VALUE:              Unsafe C macros.     (line  53)
* S48_UNSAFE_EXTRACT_VALUE_POINTER:      Unsafe C macros.     (line  54)
* S48_UNSAFE_SET_CAR:                    Unsafe C macros.     (line  22)
* S48_UNSAFE_SET_CDR:                    Unsafe C macros.     (line  23)
* S48_UNSAFE_SET_VALUE:                  Unsafe C macros.     (line  56)
* S48_UNSAFE_SHARED_BINDING_IS_IMPORTP:  Unsafe C macros.     (line  46)
* S48_UNSAFE_SHARED_BINDING_NAME:        Unsafe C macros.     (line  48)
* S48_UNSAFE_SHARED_BINDING_REF:         Unsafe C macros.     (line  44)
* S48_UNSAFE_SHARED_BINDING_SET:         Unsafe C macros.     (line  50)
* S48_UNSAFE_STRING_LENGTH:              Unsafe C macros.     (line  31)
* S48_UNSAFE_STRING_REF:                 Unsafe C macros.     (line  32)
* S48_UNSAFE_STRING_SET:                 Unsafe C macros.     (line  33)
* S48_UNSAFE_SYMBOL_TO_STRING:           Unsafe C macros.     (line  36)
* S48_UNSAFE_VECTOR_LENGTH:              Unsafe C macros.     (line  25)
* S48_UNSAFE_VECTOR_REF:                 Unsafe C macros.     (line  26)
* S48_UNSAFE_VECTOR_SET:                 Unsafe C macros.     (line  28)
* S48_UNSPECIFIC:                        Accessing Scheme data from C.
                                                              (line  16)
* s48_value:                             Accessing Scheme data from C.
                                                              (line   6)
* S48_VECTOR_LENGTH:                     Accessing Scheme data from C.
                                                              (line 114)
* S48_VECTOR_P:                          Accessing Scheme data from C.
                                                              (line 103)
* S48_VECTOR_REF:                        Accessing Scheme data from C.
                                                              (line 115)
* S48_VECTOR_SET:                        Accessing Scheme data from C.
                                                              (line 116)
* scheme-program-name:                   Emacs integration.   (line  68)
* search-tree-max:                       Library data structures.
                                                              (line  85)
* search-tree-min:                       Library data structures.
                                                              (line  86)
* search-tree-modify!:                   Library data structures.
                                                              (line  68)
* search-tree-ref:                       Library data structures.
                                                              (line  66)
* search-tree-set!:                      Library data structures.
                                                              (line  67)
* search-tree?:                          Library data structures.
                                                              (line  61)
* select:                                Rendezvous base combinators.
                                                              (line  50)
* send:                                  Rendezvous communication channels.
                                                              (line  21)
* send-async:                            Rendezvous communication channels.
                                                              (line  77)
* send-rv:                               Rendezvous communication channels.
                                                              (line  20)
* sequence:                              POSIX regular expressions.
                                                              (line 152)
* set:                                   POSIX regular expressions.
                                                              (line  91)
* set-close-on-exec?!:                   POSIX I/O utilities. (line  67)
* set-condvar-has-value?!:               Higher-level synchronization.
                                                              (line  50)
* set-condvar-value!:                    Higher-level synchronization.
                                                              (line  51)
* set-current-proposal!:                 Optimistic concurrency.
                                                              (line 270)
* set-file-creation-mask!:               POSIX file system access.
                                                              (line 122)
* set-fluid!:                            Fluid/dynamic bindings.
                                                              (line  28)
* set-group-id!:                         POSIX process environment.
                                                              (line  19)
* set-i/o-flags!:                        POSIX I/O utilities. (line  72)
* set-leaf-predicate!:                   Resource statistics and control.
                                                              (line 108)
* set-port-data!:                        Port data type.      (line  76)
* set-port-index!:                       Port data type.      (line  77)
* set-port-limit!:                       Port data type.      (line  78)
* set-port-lock!:                        Port data type.      (line  74)
* set-port-pending-eof?!:                Port data type.      (line  79)
* set-port-status!:                      Port data type.      (line  75)
* set-translation!:                      Filenames.           (line  93)
* set-user-id!:                          POSIX process environment.
                                                              (line  16)
* set-working-directory!:                POSIX file system access.
                                                              (line  33)
* shared-binding-is-import?:             Shared bindings between Scheme and C.
                                                              (line  20)
* shared-binding-ref:                    Shared bindings between Scheme and C.
                                                              (line  27)
* shared-binding-ref <1>:                Calling C functions from Scheme.
                                                              (line  85)
* shared-binding-set!:                   Shared bindings between Scheme and C.
                                                              (line  28)
* shared-binding?:                       Shared bindings between Scheme and C.
                                                              (line  19)
* shift-left:                            Pre-Scheme bitwise manipulation.
                                                              (line  14)
* signal:                                Condition system.    (line  71)
* signal <1>:                            POSIX signals.       (line  18)
* signal-condition:                      Condition system.    (line  70)
* signal-name:                           POSIX signals.       (line  22)
* signal-os-number:                      POSIX signals.       (line  23)
* signal-process:                        POSIX signals.       (line 121)
* signal-queue-monitored-signals:        POSIX signals.       (line 133)
* signal-queue?:                         POSIX signals.       (line 132)
* signal=?:                              POSIX signals.       (line  24)
* signal?:                               POSIX signals.       (line  21)
* silently:                              Ports.               (line  96)
* singleton:                             Generic dispatch system.
                                                              (line  30)
* sleep:                                 Basic thread operations.
                                                              (line  17)
* socket-accept:                         TCP & UDP sockets.   (line  30)
* socket-client:                         TCP & UDP sockets.   (line  37)
* socket-port-number:                    TCP & UDP sockets.   (line  11)
* some-values:                           Static type system.  (line 120)
* space:                                 Resource statistics and control.
                                                              (line  63)
* sparse-vector->list:                   Library data structures.
                                                              (line 119)
* sparse-vector-ref:                     Library data structures.
                                                              (line 110)
* sparse-vector-set!:                    Library data structures.
                                                              (line 111)
* spawn:                                 Basic thread operations.
                                                              (line   8)
* stream%:                               Synchronous sequences.
                                                              (line  25)
* stream*:                               Sequence types.      (line  11)
* string%:                               Synchronous sequences.
                                                              (line  22)
* string*:                               Sequence types.      (line   8)
* string->immutable-string:              Library utilities.   (line 205)
* string-end:                            POSIX regular expressions.
                                                              (line 144)
* string-hash:                           Miscellaneous features.
                                                              (line  31)
* string-hash <1>:                       Hash tables.         (line  52)
* string-length:                         Compound Pre-Scheme data manipulation.
                                                              (line  30)
* string-output-port-output:             I/O extensions.      (line  45)
* string-ref:                            Compound Pre-Scheme data manipulation.
                                                              (line  31)
* string-set!:                           Compound Pre-Scheme data manipulation.
                                                              (line  32)
* string-start:                          POSIX regular expressions.
                                                              (line 143)
* strongly-connected-components:         Library utilities.   (line  67)
* structure:                             Module configuration language.
                                                              (line 135)
* structure-ref:                         Module configuration language.
                                                              (line  23)
* structures:                            Module configuration language.
                                                              (line 136)
* sublist:                               Various utilities.   (line 117)
* submatch:                              POSIX regular expressions.
                                                              (line 214)
* subset:                                Module configuration language.
                                                              (line 142)
* subtract:                              POSIX regular expressions.
                                                              (line 111)
* sync:                                  Rendezvous base combinators.
                                                              (line  49)
* syntax-error:                          Condition system.    (line  80)
* syntax-error?:                         Condition system.    (line 196)
* table-ref:                             Hash tables.         (line  33)
* table-set!:                            Hash tables.         (line  34)
* table-walk:                            Hash tables.         (line  42)
* table?:                                Hash tables.         (line  30)
* template:                              Inspector.           (line  58)
* terminate-current-thread:              Basic thread operations.
                                                              (line  23)
* text:                                  POSIX regular expressions.
                                                              (line 158)
* thread-name:                           Basic thread operations.
                                                              (line  32)
* thread-queue-empty?:                   Custom thread synchronization.
                                                              (line  41)
* thread-uid:                            Basic thread operations.
                                                              (line  33)
* thread?:                               Basic thread operations.
                                                              (line  31)
* time->string:                          POSIX time.          (line  33)
* time-seconds:                          POSIX time.          (line  14)
* time<=?:                               POSIX time.          (line  23)
* time<?:                                POSIX time.          (line  22)
* time=?:                                POSIX time.          (line  21)
* time>=?:                               POSIX time.          (line  25)
* time>?:                                POSIX time.          (line  24)
* time?:                                 POSIX time.          (line  13)
* trail:                                 Resource statistics and control.
                                                              (line 103)
* translate:                             Filenames.           (line  97)
* translations:                          Filenames.           (line  90)
* traverse-breadth-first:                Resource statistics and control.
                                                              (line  86)
* traverse-depth-first:                  Resource statistics and control.
                                                              (line  87)
* u:                                     Inspector.           (line  51)
* udp-address-address:                   TCP & UDP sockets.   (line  66)
* udp-address-hostname:                  TCP & UDP sockets.   (line  68)
* udp-address-port:                      TCP & UDP sockets.   (line  67)
* udp-address?:                          TCP & UDP sockets.   (line  65)
* udp-receive:                           TCP & UDP sockets.   (line  55)
* udp-send:                              TCP & UDP sockets.   (line  54)
* undefine-exported-binding:             Shared bindings between Scheme and C.
                                                              (line  46)
* undefine-imported-binding:             Shared bindings between Scheme and C.
                                                              (line  35)
* union:                                 POSIX regular expressions.
                                                              (line 108)
* unlink:                                POSIX file system access.
                                                              (line 136)
* unload-dynamic-externals:              Dynamic loading of C modules.
                                                              (line  14)
* unsigned-byte-ref:                     Low-level Pre-Scheme memory manipulation.
                                                              (line  26)
* unsigned-byte-set!:                    Low-level Pre-Scheme memory manipulation.
                                                              (line  27)
* unspecific:                            Various utilities.   (line  12)
* upper-case:                            POSIX regular expressions.
                                                              (line 124)
* use-case:                              POSIX regular expressions.
                                                              (line 182)
* user-id->integer:                      POSIX users and groups.
                                                              (line  14)
* user-id->user-info:                    POSIX users and groups.
                                                              (line  27)
* user-id=?:                             POSIX users and groups.
                                                              (line  13)
* user-id?:                              POSIX users and groups.
                                                              (line  12)
* user-info-group:                       POSIX users and groups.
                                                              (line  37)
* user-info-home-directory:              POSIX users and groups.
                                                              (line  38)
* user-info-id:                          POSIX users and groups.
                                                              (line  36)
* user-info-name:                        POSIX users and groups.
                                                              (line  35)
* user-info-shell:                       POSIX users and groups.
                                                              (line  39)
* user-info?:                            POSIX users and groups.
                                                              (line  34)
* usual-leaf-predicate:                  Resource statistics and control.
                                                              (line 109)
* usual-resumer:                         Suspending and resuming heap images.
                                                              (line  53)
* values:                                Module configuration language.
                                                              (line 198)
* values <1>:                            Scheme bindings in Pre-Scheme.
                                                              (line  38)
* variable:                              Static type system.  (line 190)
* vector%:                               Synchronous sequences.
                                                              (line  21)
* vector*:                               Sequence types.      (line   7)
* vector-length:                         Compound Pre-Scheme data manipulation.
                                                              (line  13)
* vector-ref:                            Compound Pre-Scheme data manipulation.
                                                              (line  14)
* vector-set!:                           Compound Pre-Scheme data manipulation.
                                                              (line  15)
* vector-space:                          Resource statistics and control.
                                                              (line  64)
* wait-for-channel:                      Channels.            (line 157)
* wait-for-child-process:                POSIX processes.     (line  29)
* walk-population:                       Weak references.     (line  30)
* walk-search-tree:                      Library data structures.
                                                              (line  96)
* warn:                                  Condition system.    (line  79)
* warning?:                              Condition system.    (line 194)
* weak-pointer-ref:                      Weak references.     (line  15)
* weak-pointer?:                         Weak references.     (line  14)
* whitespace:                            POSIX regular expressions.
                                                              (line 135)
* with-current-ports:                    Ports.               (line 101)
* with-handler:                          Condition system.    (line 127)
* with-input-from-file:                  Channel ports.       (line  12)
* with-nack:                             Rendezvous base combinators.
                                                              (line  17)
* with-new-proposal:                     Optimistic concurrency.
                                                              (line 288)
* with-nondeterminism:                   Library utilities.   (line  87)
* with-output-to-file:                   Channel ports.       (line  13)
* with-prefix:                           Module configuration language.
                                                              (line 143)
* word-ref:                              Low-level Pre-Scheme memory manipulation.
                                                              (line  28)
* word-set!:                             Low-level Pre-Scheme memory manipulation.
                                                              (line  29)
* working-directory:                     POSIX file system access.
                                                              (line  32)
* wrap:                                  Rendezvous base combinators.
                                                              (line  38)
* write:                                 Writer.              (line  10)
* write-block:                           Ports.               (line  41)
* write-block <1>:                       Low-level Pre-Scheme memory manipulation.
                                                              (line 108)
* write-char:                            Input & output in Pre-Scheme.
                                                              (line  41)
* write-image:                           Suspending and resuming heap images.
                                                              (line  25)
* write-integer:                         Input & output in Pre-Scheme.
                                                              (line  44)
* write-string:                          Ports.               (line  42)
* write-string <1>:                      Input & output in Pre-Scheme.
                                                              (line  43)