   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

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

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

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

Evaluator trap options
----------------------

   [FIXME: These flags, together with their corresponding handlers, are
not user level options.  Probably this entire section should be moved
to the documentation about the low-level programmer debugging
interface.]

   Here is the list of evaluator trap options generated by typing
`(traps 'full)' in Guile.  You can also see the default values.

     exit-frame      no      Trap when exiting eval or apply.
     apply-frame     no      Trap when entering apply.
     enter-frame     no      Trap when eval enters new frame.
     traps		yes	Enable evaluator traps.

 - apply-frame-handler: key cont tailp
     Called when a procedure is being applied.

     Called if:

        * evaluator traps are enabled [traps interface], and

        * either
             - `apply-frame' is enabled [traps interface], or

             - trace mode is on [debug-options interface], and the
               procedure being called has the trace property enabled.

     If cheap traps are enabled [debug-options interface], CONT is a
     debug object, otherwise it is a restartable continuation.

     TAILP is true if this is a tail call

 - exit-frame-handler: key cont retval
     Called when a value is returned from a procedure.

     Called if:

        * evaluator traps are enabled [traps interface], and

        * either
             -  `exit-frame' is enabled [traps interface], or

             - trace mode is on [debug-options interface], and the
               procedure being called has the trace property enabled.

     If cheap traps are enabled [debug-options interface], CONT is a
     debug object, otherwise it is a restartable continuation.

     RETVAL is the return value.

Debugger options
----------------

   Here is the list of print options generated by typing
`(debug-options 'full)' in Guile.  You can also see the default values.

     stack           20000   Stack size limit (0 = no check).
     debug           yes     Use the debugging evaluator.
     backtrace       no      Show backtrace on error.
     depth           20      Maximal length of printed backtrace.
     maxdepth        1000    Maximal number of stored backtrace frames.
     frames          3       Maximum number of tail-recursive frames in backtrace.
     indent          10      Maximal indentation in backtrace.
     backwards       no      Display backtrace in anti-chronological order.
     procnames       yes     Record procedure names at definition.
     trace           no      *Trace mode.
     breakpoints     no      *Check for breakpoints.
     cheap           yes     *Flyweight representation of the stack at traps.

Stack overflow
..............

   Stack overflow errors are caused by a computation trying to use more
stack space than has been enabled by the `stack' option.  They are
reported like this:

     (non-tail-recursive-factorial 500)
     -|
     ERROR: Stack overflow
     ABORT: (stack-overflow)

   If you get an error like this, you can either try rewriting your
code to use less stack space, or increase the maximum stack size.  To
increase the maximum stack size, use `debug-set!', for example:

     (debug-set! stack 200000)
     =>
     (show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap)

     (non-tail-recursive-factorial 500)
     =>
     122013682599111006870123878542304692625357434...

   If you prefer to try rewriting your code, you may be able to save
stack space by making some of your procedures "tail recursive".  For a
description of what this means, see Proper tail recursion (r5rs).

Examples of option use
----------------------

   Here is an example of a session in which some read and debug option
handling procedures are used.  In this example, the user

  1. Notices that the symbols `abc' and `aBc' are not the same

  2. Examines the `read-options', and sees that `case-insensitive' is
     set to "no".

  3. Enables `case-insensitive'

  4. Verifies that now `aBc' and `abc' are the same

  5. Disables `case-insensitive' and enables debugging `backtrace'

  6. Reproduces the error of displaying `aBc' with backtracing enabled
     [FIXME: this last example is lame because there is no depth in the
     backtrace.  Need to give a better example, possibly putting
     debugging option examples in a separate session.]

     guile> (define abc "hello")
     guile> abc
     "hello"
     guile> aBc
     ERROR: In expression aBc:
     ERROR: Unbound variable: aBc
     ABORT: (misc-error)

     Type "(backtrace)" to get more information.
     guile> (read-options 'help)
     keywords	#f	Style of keyword recognition: #f or 'prefix
     case-insensitive	no	Convert symbols to lower case.
     positions	yes	Record positions of source code expressions.
     copy		no	Copy source code expressions.
     guile> (debug-options 'help)
     stack		20000	Stack size limit (0 = no check).
     debug		yes	Use the debugging evaluator.
     backtrace	no	Show backtrace on error.
     depth		20	Maximal length of printed backtrace.
     maxdepth	1000	Maximal number of stored backtrace frames.
     frames		3	Maximum number of tail-recursive frames in backtrace.
     indent		10	Maximal indentation in backtrace.
     backwards	no	Display backtrace in anti-chronological order.
     procnames	yes	Record procedure names at definition.
     trace		no	*Trace mode.
     breakpoints	no	*Check for breakpoints.
     cheap		yes	*Flyweight representation of the stack at traps.
     guile> (read-enable 'case-insensitive)
     (keywords #f case-insensitive positions)
     guile> aBc
     "hello"
     guile> (read-disable 'case-insensitive)
     (keywords #f positions)
     guile> (debug-enable 'backtrace)
     (stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap)
     guile> aBc

     Backtrace:
     0* aBc

     ERROR: In expression aBc:
     ERROR: Unbound variable: aBc
     ABORT: (misc-error)
     guile>

Support for Translating Other Languages
***************************************

   [Describe translation framework.]

Emacs Lisp Support
==================

 - Scheme Procedure: nil-car x
 - C Function: scm_nil_car (x)
     Return the car of X, but convert it to LISP nil if it is Scheme's
     end-of-list.

 - Scheme Procedure: nil-cdr x
 - C Function: scm_nil_cdr (x)
     Return the cdr of X, but convert it to LISP nil if it is Scheme's
     end-of-list.

 - Scheme Procedure: nil-cons x y
 - C Function: scm_nil_cons (x, y)
     Create a new cons cell with X as the car and Y as the cdr, but
     convert Y to Scheme's end-of-list if it is a Lisp nil.

 - Scheme Procedure: nil-eq x y
     Compare X and Y and return Lisp's t if they are `eq?', return
     Lisp's nil otherwise.

 - Scheme Procedure: null x
 - C Function: scm_null (x)
     Return Lisp's `t' if X is nil in the LISP sense, return Lisp's nil
     otherwise.

Debugging Infrastructure
************************

Source Properties
=================

   As Guile reads in Scheme code from file or from standard input, it
remembers the file name, line number and column number where each
expression begins.  These pieces of information are known as the
"source properties" of the expression.  If an expression undergoes
transformation -- for example, if there is a syntax transformer in
effect, or the expression is a macro call -- the source properties are
copied from the untransformed to the transformed expression so that, if
an error occurs when evaluating the transformed expression, Guile's
debugger can point back to the file and location where the expression
originated.

   The way that source properties are stored means that Guile can only
associate source properties with parenthesized expressions, and not, for
example, with individual symbols, numbers or strings.  The difference
can be seen by typing `(xxx)' and `xxx' at the Guile prompt (where the
variable `xxx' has not been defined):

     guile> (xxx)
     standard input:2:1: In expression (xxx):
     standard input:2:1: Unbound variable: xxx
     ABORT: (unbound-variable)
     guile> xxx
     <unnamed port>: In expression xxx:
     <unnamed port>: Unbound variable: xxx
     ABORT: (unbound-variable)

In the latter case, no source properties were stored, so the best that
Guile could say regarding the location of the problem was "<unnamed
port>".

   The recording of source properties is controlled by the read option
named "positions" (see Reader options).  This option is switched
_on_ by default, together with the debug options "debug" and
"backtrace" (see Debugger options), when Guile is run
interactively; all these options are _off_ by default when Guile runs a
script non-interactively.

Using Traps
===========

 - Scheme Procedure: with-traps thunk
 - C Function: scm_with_traps (thunk)
     Call THUNK with traps enabled.

 - Scheme Procedure: debug-object? obj
 - C Function: scm_debug_object_p (obj)
     Return `#t' if OBJ is a debug object.

Capturing the Stack or Innermost Stack Frame
============================================

   When an error occurs in a running program, or the program hits a
breakpoint, its state at that point can be represented by a "stack" of
all the evaluations and procedure applications that are logically in
progress at that time, each of which is known as a "frame".  The
programmer can learn more about the program's state at the point of
interruption or error by inspecting the stack and its frames.

 - Scheme Procedure: make-stack obj . args
 - C Function: scm_make_stack (obj, args)
     Create a new stack. If OBJ is `#t', the current evaluation stack
     is used for creating the stack frames, otherwise the frames are
     taken from OBJ (which must be either a debug object or a
     continuation).

     ARGS should be a list containing any combination of integer,
     procedure and `#t' values.

     These values specify various ways of cutting away uninteresting
     stack frames from the top and bottom of the stack that
     `make-stack' returns.  They come in pairs like this: `(INNER_CUT_1
     OUTER_CUT_1 INNER_CUT_2 OUTER_CUT_2 ...)'.

     Each INNER_CUT_N can be `#t', an integer, or a procedure.  `#t'
     means to cut away all frames up to but excluding the first user
     module frame.  An integer means to cut away exactly that number of
     frames.  A procedure means to cut away all frames up to but
     excluding the application frame whose procedure matches the
     specified one.

     Each OUTER_CUT_N can be an integer or a procedure.  An integer
     means to cut away that number of frames.  A procedure means to cut
     away frames down to but excluding the application frame whose
     procedure matches the specified one.

     If the OUTER_CUT_N of the last pair is missing, it is taken as 0.

 - Scheme Procedure: last-stack-frame obj
 - C Function: scm_last_stack_frame (obj)
     Return a stack which consists of a single frame, which is the last
     stack frame for OBJ. OBJ must be either a debug object or a
     continuation.

Examining the Stack
===================

 - Scheme Procedure: stack? obj
 - C Function: scm_stack_p (obj)
     Return `#t' if OBJ is a calling stack.

 - Scheme Procedure: stack-id stack
 - C Function: scm_stack_id (stack)
     Return the identifier given to STACK by `start-stack'.

 - Scheme Procedure: stack-length stack
 - C Function: scm_stack_length (stack)
     Return the length of STACK.

 - Scheme Procedure: stack-ref stack index
 - C Function: scm_stack_ref (stack, index)
     Return the INDEX'th frame from STACK.

 - Scheme Procedure: display-backtrace stack port [first [depth]]
 - C Function: scm_display_backtrace (stack, port, first, depth)
     Display a backtrace to the output port PORT. STACK is the stack to
     take the backtrace from, FIRST specifies where in the stack to
     start and DEPTH how much frames to display. Both FIRST and DEPTH
     can be `#f', which means that default values will be used.

Examining Stack Frames
======================

 - Scheme Procedure: frame? obj
 - C Function: scm_frame_p (obj)
     Return `#t' if OBJ is a stack frame.

 - Scheme Procedure: frame-number frame
 - C Function: scm_frame_number (frame)
     Return the frame number of FRAME.

 - Scheme Procedure: frame-previous frame
 - C Function: scm_frame_previous (frame)
     Return the previous frame of FRAME, or `#f' if FRAME is the first
     frame in its stack.

 - Scheme Procedure: frame-next frame
 - C Function: scm_frame_next (frame)
     Return the next frame of FRAME, or `#f' if FRAME is the last frame
     in its stack.

 - Scheme Procedure: frame-source frame
 - C Function: scm_frame_source (frame)
     Return the source of FRAME.

 - Scheme Procedure: frame-procedure? frame
 - C Function: scm_frame_procedure_p (frame)
     Return `#t' if a procedure is associated with FRAME.

 - Scheme Procedure: frame-procedure frame
 - C Function: scm_frame_procedure (frame)
     Return the procedure for FRAME, or `#f' if no procedure is
     associated with FRAME.

 - Scheme Procedure: frame-arguments frame
 - C Function: scm_frame_arguments (frame)
     Return the arguments of FRAME.

 - Scheme Procedure: frame-evaluating-args? frame
 - C Function: scm_frame_evaluating_args_p (frame)
     Return `#t' if FRAME contains evaluated arguments.

 - Scheme Procedure: frame-overflow? frame
 - C Function: scm_frame_overflow_p (frame)
     Return `#t' if FRAME is an overflow frame.

 - Scheme Procedure: frame-real? frame
 - C Function: scm_frame_real_p (frame)
     Return `#t' if FRAME is a real frame.

 - Scheme Procedure: display-application frame [port [indent]]
 - C Function: scm_display_application (frame, port, indent)
     Display a procedure application FRAME to the output port PORT.
     INDENT specifies the indentation of the output.

Decoding Memoized Source Expressions
====================================

 - Scheme Procedure: memoized? obj
 - C Function: scm_memoized_p (obj)
     Return `#t' if OBJ is memoized.

 - Scheme Procedure: unmemoize m
 - C Function: scm_unmemoize (m)
     Unmemoize the memoized expression M,

 - Scheme Procedure: memoized-environment m
 - C Function: scm_memoized_environment (m)
     Return the environment of the memoized expression M.

Starting a New Stack
====================

 - Scheme Syntax: start-stack id exp
     Evaluate EXP on a new calling stack with identity ID.  If EXP is
     interrupted during evaluation, backtraces will not display frames
     farther back than EXP's top-level form.  This macro is a way of
     artificially limiting backtraces and stack procedures, largely as
     a convenience to the user.

Deprecated
**********

Shared And Read Only Strings
============================

   The procedures described in this section are deprecated because
explicit shared substrings are planned to disappear from Guile.

   Instead, all strings will be implemented using sharing internally,
combined with a copy-on-write strategy.  Once internal string sharing
and copy-on-write have been implemented, it will be unnecessary to
preserve the concept of read only strings.

Shared Substrings
-----------------

   Whenever you extract a substring using `substring', the Scheme
interpreter allocates a new string and copies data from the old string.
This is expensive, but `substring' is so convenient for manipulating
text that programmers use it often.

   Guile Scheme provides the concept of the "shared substring" to
improve performance of many substring-related operations.  A shared
substring is an object that mostly behaves just like an ordinary
substring, except that it actually shares storage space with its parent
string.

 - Deprecated Scheme Procedure: make-shared-substring str [start [end]]
 - Deprecated C Function: scm_make_shared_substring (str, start, end)
     Return a shared substring of STR.  The arguments are the same as
     for the `substring' function: the shared substring returned
     includes all of the text from STR between indexes START
     (inclusive) and END (exclusive).  If END is omitted, it defaults
     to the end of STR.  The shared substring returned by
     `make-shared-substring' occupies the same storage space as STR.

   Example:

     (define foo "the quick brown fox")
     (define bar (make-shared-substring some-string 4 9))

     foo => "t h e   q u i c k   b r o w n   f o x"
     bar =========> |---------|

   The shared substring BAR is not given its own storage space.
Instead, the Guile interpreter notes internally that BAR points to a
portion of the memory allocated to FOO.  However, BAR behaves like an
ordinary string in most respects: it may be used with string primitives
like `string-length', `string-ref', `string=?'.  Guile makes the
necessary translation between indices of BAR and indices of FOO
automatically.

     (string-length? bar) => 5	; bar only extends from indices 4 to 9
     (string-ref bar 3)  => #\c	; same as (string-ref foo 7)
     (make-shared-substring bar 2)
       => "ick"			; can even make a shared substring!

   Because creating a shared substring does not require allocating new
storage from the heap, it is a very fast operation.  However, because it
shares memory with its parent string, a change to the contents of the
parent string will implicitly change the contents of its shared
substrings.

     (string-set! foo 7 #\r)
     bar => "quirk"

   Guile considers shared substrings to be immutable.  This is because
programmers might not always be aware that a given string is really a
shared substring, and might innocently try to mutate it without
realizing that the change would affect its parent string.  (We are
currently considering a "copy-on-write" strategy that would permit
modifying shared substrings without affecting the parent string.)

   In general, shared substrings are useful in circumstances where it is
important to divide a string into smaller portions, but you do not
expect to change the contents of any of the strings involved.

Read Only Strings
-----------------

   In previous versions of Guile, there was the idea that some
string-based primitives such as `string-append' could equally accept
symbols as arguments.  For example, one could write

     (string-append '/home/ 'vigilia)

and get `"/home/vigilia"' as the result.  The term "read only string"
was adopted to describe the argument type expected by such primitives.

   This idea has now been removed.  The predicate `read-only-string?'
still exists, but deprecated, and is equivalent to

     (lambda (x) (or (string? x) (symbol? x)))

But no Guile primitives now use `read-only-string?' to validate their
arguments.

   String-based primitives such as `string-append' now require strings:

     (string-append '/home/ 'vigilia)
     =>
     ERROR: Wrong type argument (expecting STRINGP): /home/

 - Deprecated Scheme Procedure: read-only-string? obj
 - Deprecated C Function: scm_read_only_string_p (obj)
     Return `#t' if OBJ is either a string or a symbol, otherwise
     return `#f'.

`Sloppy' List Membership Procedures
===================================

   The following are equivalent to `memq', `memv' and `member'
respectively, except that they do not fully type-check the arguments
that they are given.  They are deprecated because the lack of proper
type-checking makes them dangerous.

 - Deprecated Scheme Procedure: sloppy-memq x lst
 - Deprecated C Function: scm_sloppy_memq (x, lst)
     This procedure behaves like `memq', but does no type or error
     checking.  Its use is recommended only in writing Guile internals,
     not for high-level Scheme programs.

 - Deprecated Scheme Procedure: sloppy-memv x lst
 - Deprecated C Function: scm_sloppy_memv (x, lst)
     This procedure behaves like `memv', but does no type or error
     checking.  Its use is recommended only in writing Guile internals,
     not for high-level Scheme programs.

 - Deprecated Scheme Procedure: sloppy-member x lst
 - Deprecated C Function: scm_sloppy_member (x, lst)
     This procedure behaves like `member', but does no type or error
     checking.  Its use is recommended only in writing Guile internals,
     not for high-level Scheme programs.

Strange Variations on `eval'
============================

   `eval2' was useful in previous Guile releases because the `eval' in
those releases was a single argument `eval' that did not conform to
R5RS.  Guile's standard `eval' now requires a second
environment-specifier argument (which Guile interprets as the module in
which to evaluate the specified code expression).  Hence `eval' is now
R5RS-compliant, and `eval2' is obsolete and therefore deprecated.

 - Deprecated Scheme Procedure: eval2 obj env_thunk
 - Deprecated C Function: scm_eval2 (obj, env_thunk)
     Evaluate EXP, a Scheme expression, in the environment designated
     by LOOKUP, a symbol-lookup function.  Do not use this version of
     eval, it does not play well with the module system.  Use `eval' or
     `primitive-eval' instead.

   In previous Guile releases, the implementation of expressions like
`(eval (read port))' was deficient in that source properties associated
with the expression returned by the `read' would be lost during the
`eval'.  To provide a way of performing a read and evaluation without
losing source properties, `read-and-eval!' was invented.

   In this Guile release, evaluation always preserves source property
information.  So `read-and-eval!' is now unnecessary.

 - Deprecated Scheme Procedure: read-and-eval! [port]
 - Deprecated C Function: scm_read_and_eval_x (port)
     Read a form from PORT (standard input by default), and evaluate it
     (memoizing it in the process) in the top-level environment.  If no
     data is left to be read from PORT, an `end-of-file' error is
     signalled.

Closing All Ports Except Some ...
=================================

 - Deprecated Scheme Procedure: close-all-ports-except . ports
 - Deprecated C Function: scm_close_all_ports_except (ports)
     [DEPRECATED] Close all open file ports used by the interpreter
     except for those supplied as arguments.  This procedure was
     intended to be used before an exec call to close file descriptors
     which are not needed in the new process.  However it has the
     undesirable side effect of flushing buffers, so it's deprecated.
     Use port-for-each instead.

Old Method for Registering C Modules.
=====================================

   ** Auto-loading of compiled-code modules is deprecated.

   Guile used to be able to automatically find and link a shared
library to satisfy requests for a module.  For example, the module
`(foo bar)' could be implemented by placing a shared library named
"foo/libbar.so" (or with a different extension) in a directory on the
load path of Guile.

   This has been found to be too tricky, and is no longer supported.
The shared libraries are now called "extensions".  You should now write
a small Scheme file that calls `load-extension' to load the shared
library and initialize it explicitely.

   The shared libraries themselves should be installed in the usual
places for shared libraries, with names like "libguile-foo-bar".

   For example, place this into a file "foo/bar.scm"

   (define-module (foo bar))

   (load-extension "libguile-foo-bar" "foobar_init")

Obarray Symbol Manipulation
===========================

   Guile's module mechanism uses "obarrays", which are hash tables that
map symbols to variables.  Guile 1.4 included a group of primitives that
could be used for the manipulation of the symbol-variable mappings in
such obarrays.

   However, considering the availability both of low-level procedures
for operating on hash tables in general (see Hash Tables), and of a
dedicated API for module-related operations (see Modules), the
intermediate set of obarray primitives is no longer useful, and --
which is worse -- makes it more difficult to evolve the implementation
of Guile's module system.  Hence this set of primitives has now been
deprecated.

   If you have code using these functions, please change it to use
either hash table or module-related operations.

 - Deprecated Scheme Procedure: gentemp [prefix [obarray]]
 - Deprecated C Function: scm_gentemp (prefix, obarray)
     Create a new symbol with a name unique in an obarray.  The name is
     constructed from an optional string PREFIX and a counter value.
     The default prefix is `t'.  The OBARRAY is specified as a second
     optional argument.  Default is the system obarray where all normal
     symbols are interned.  The counter is increased by 1 at each call.
     There is no provision for resetting the counter.

 - Deprecated Scheme Procedure: intern-symbol obarray string
 - Deprecated C Function: scm_intern_symbol (obarray, string)
     Add a new symbol to OBARRAY with name STRING, bound to an
     unspecified initial value.  The symbol table is not modified if a
     symbol with this name is already present.

 - Deprecated Scheme Procedure: symbol-interned? obarray string
 - Deprecated C Function: scm_symbol_interned_p (obarray, string)
     Return `#t' if OBARRAY contains a symbol with name STRING, and
     `#f' otherwise.

 - Deprecated Scheme Procedure: unintern-symbol obarray string
 - Deprecated C Function: scm_unintern_symbol (obarray, string)
     Remove the symbol with name STRING from OBARRAY.  This function
     returns `#t' if the symbol was present and `#f' otherwise.

 - Deprecated Scheme Procedure: string->obarray-symbol obarray string
          [soft?]
 - Deprecated C Function: scm_string_to_obarray_symbol (obarray,
          string, soft_p)
     Intern a new symbol in OBARRAY, a symbol table, with name STRING.

     If OBARRAY is `#f', use the default system symbol table.  If
     OBARRAY is `#t', the symbol should not be interned in any symbol
     table; merely return the pair (SYMBOL . #<UNDEFINED>).

     The SOFT? argument determines whether new symbol table entries
     should be created when the specified symbol is not already present
     in OBARRAY.  If SOFT? is specified and is a true value, then new
     entries should not be added for symbols not already present in the
     table; instead, simply return `#f'.

 - Deprecated Scheme Procedure: symbol-binding obarray string
 - Deprecated C Function: scm_symbol_binding (obarray, string)
     Look up in OBARRAY the symbol whose name is STRING, and return the
     value to which it is bound.  If OBARRAY is `#f', use the global
     symbol table.  If STRING is not interned in OBARRAY, an error is
     signalled.

 - Deprecated Scheme Procedure: symbol-bound? obarray string
 - Deprecated C Function: scm_symbol_bound_p (obarray, string)
     Return `#t' if OBARRAY contains a symbol with name STRING bound to
     a defined value.  This differs from SYMBOL-INTERNED? in that the
     mere mention of a symbol usually causes it to be interned;
     `symbol-bound?' determines whether a symbol has been given any
     meaningful value.

 - Deprecated Scheme Procedure: symbol-set! obarray string value
 - Deprecated C Function: scm_symbol_set_x (obarray, string, value)
     Find the symbol in OBARRAY whose name is STRING, and rebind it to
     VALUE.  An error is signalled if STRING is not present in OBARRAY.

 - Deprecated Scheme Procedure: builtin-bindings
 - Deprecated C Function: scm_builtin_bindings
     Create and return a copy of the global symbol table, removing all
     unbound symbols.

Previously Deprecated Items Now Removed
=======================================

   tag fseek list*

SLIB
****

   Before the SLIB facilities can be used, the following Scheme
expression must be executed:

     (use-modules (ice-9 slib))

   `require' can then be used as described in SLIB (slib).

   For example:

     guile> (use-modules (ice-9 slib))
     guile> (require 'primes)
     guile> (probably-prime? 13)

SLIB installation
=================

   The following seems to work (e.g., with slib versions 2c7 and 2d2):

  1. Unpack slib somewhere, e.g., /usr/local/share/slib.

  2. Create a symlink in the Guile site directory to slib, e.g.,:

          ln -s /usr/local/share/slib /usr/local/share/guile/site/slib

  3. Use Guile to create the catalog file, e.g.,:

          # guile
          guile> (use-modules (ice-9 slib))
          guile> (load "/usr/local/share/slib/mklibcat.scm")
          guile> (quit)

     The catalog data should now be in
     `/usr/local/share/guile/site/slibcat'.

     If instead you get an error such as:

          Unbound variable: scheme-implementation-type

     then a solution is to get a newer version of Guile, or to modify
     ice-9/slib.scm to use define-public for the offending variables.

  4. Install the documentation:

          cd /usr/local/share/slib
          rm /usr/local/info/slib.info*
          cp slib.info /usr/local/info
          install-info slib.info /usr/local/info/dir

JACAL
=====

   Jacal is a symbolic math package written in Scheme by Aubrey Jaffer.
It is usually installed as an extra package in SLIB (see Packages not shipped with Guile).

   You can use Guile's interface to SLIB to invoke Jacal:

     (use-modules (ice-9 slib))
     (slib:load "math")
     (math)

For complete documentation on Jacal, please read the Jacal manual.  If
it has been installed on line, you can look at Jacal (jacal).
Otherwise you can find it on the web at
<http://www-swiss.ai.mit.edu/~jaffer/JACAL.html>

POSIX System Calls and Networking
*********************************

POSIX Interface Conventions
===========================

   These interfaces provide access to operating system facilities.
They provide a simple wrapping around the underlying C interfaces to
make usage from Scheme more convenient.  They are also used to
implement the Guile port of The Scheme shell (scsh).

   Generally there is a single procedure for each corresponding Unix
facility.  There are some exceptions, such as procedures implemented for
speed and convenience in Scheme with no primitive Unix equivalent,
e.g., `copy-file'.

   The interfaces are intended as far as possible to be portable across
different versions of Unix.  In some cases procedures which can't be
implemented on particular systems may become no-ops, or perform limited
actions.  In other cases they may throw errors.

   General naming conventions are as follows:

   * The Scheme name is often identical to the name of the underlying
     Unix facility.

   * Underscores in Unix procedure names are converted to hyphens.

   * Procedures which destructively modify Scheme data have exclamation
     marks appended, e.g., `recv!'.

   * Predicates (returning only `#t' or `#f') have question marks
     appended, e.g., `access?'.

   * Some names are changed to avoid conflict with dissimilar interfaces
     defined by scsh, e.g., `primitive-fork'.

   * Unix preprocessor names such as `EPERM' or `R_OK' are converted to
     Scheme variables of the same name (underscores are not replaced
     with hyphens).

   Unexpected conditions are generally handled by raising exceptions.
There are a few procedures which return a special value if they don't
succeed, e.g., `getenv' returns `#f' if it the requested string is not
found in the environment.  These cases are noted in the documentation.

   For ways to deal with exceptions, see Exceptions.

   Errors which the C-library would report by returning a NULL pointer
or through some other means are reported by raising a `system-error'
exception.  The value of the Unix `errno' variable is available in the
data passed by the exception.

   It can be extracted with the function `system-error-errno':

     (catch
      'system-error
      (lambda ()
        (mkdir "/this-ought-to-fail-if-I'm-not-root"))
      (lambda stuff
        (let ((errno (system-error-errno stuff)))
          (cond
           ((= errno EACCES)
            (display "You're not allowed to do that."))
           ((= errno EEXIST)
            (display "Already exists."))
           (#t
            (display (strerror errno))))
          (newline))))