   This is a Texinfo GCL SYSTEM INTERNALS Manual

   Copyright 1994 William F. Schelter

System Definitions
******************

 - Function: ALLOCATE-CONTIGUOUS-PAGES (NUMBER &optional
          (REALLY-ALLOCATE NIL))
     Package:SI

     GCL specific: Sets the maximum number of pages for contiguous
     blocks to NUMBER.  If REALLY-ALLOCATE is non-NIL, then the
     specified number of pages will be allocated immediately.

 - Function: FREEZE-DEFSTRUCT (NAME)
     Package:SI

     The inline defstruct type checker will be made more efficient, in
     that it will only check for types which currently include NAME.
     After calling this the defstruct should not be altered.

 - Function: MAXIMUM-ALLOCATABLE-PAGES (TYPE)
     Package:SI

     GCL specific: Returns the current maximum number of pages for the
     type class of the GCL implementation type TYPE.

 - Function: ALLOCATED-RELOCATABLE-PAGES ()
     Package:SI

     GCL specific: Returns the number of pages currently allocated for
     relocatable blocks.

 - Function: PUTPROP (SYMBOL VALUE INDICATOR)
     Package:SI

     Give SYMBOL the VALUE on INDICATOR property.

 - Function: ALLOCATED-PAGES (TYPE)
     Package:SI

     GCL specific: Returns the number of pages currently allocated for
     the type class of the GCL implementation type TYPE.

 - Function: ALLOCATE-RELOCATABLE-PAGES (NUMBER)
     Package:SI

     GCL specific: Sets the maximum number of pages for relocatable
     blocks to NUMBER.

 - Function: ALLOCATED-CONTIGUOUS-PAGES ()
     Package:SI

     GCL specific: Returns the number of pages currently allocated for
     contiguous blocks.

 - Function: MAXIMUM-CONTIGUOUS-PAGES ()
     Package:SI

     GCL specific: Returns the current maximum number of pages for
     contiguous blocks.

 - Function: GET-HOLE-SIZE ()
     Package:SI

     GCL specific: Returns as a fixnum the size of the memory hole (in
     pages).

 - Function: SPECIALP (SYMBOL)
     Package:SI

     GCL specific: Returns T if the SYMBOL is a globally special
     variable; NIL otherwise.

 - Function: OUTPUT-STREAM-STRING (STRING-OUTPUT-STREAM)
     Package:SI

     GCL specific: Returns the string corresponding to the
     STRING-OUTPUT-STREAM.

 - Function: GET-STRING-INPUT-STREAM-INDEX (STRING-INPUT-STREAM)
     Package:SI

     GCL specific: Returns the current index of the STRING-INPUT-STREAM.

 - Function: STRING-CONCATENATE (&rest STRINGS)
     Package:SI

     GCL specific: Returns the result of concatenating the given
     STRINGS.

 - Function: BDS-VAR (I)
     Package:SI

     GCL specific: Returns the symbol of the i-th entity in the bind
     stack.

 - Function: ERROR-SET (FORM)
     Package:SI

     GCL specific: Evaluates the FORM in the null environment.  If the
     evaluation of the FORM has successfully completed, SI:ERROR-SET
     returns NIL as the first value and the result of the evaluation as
     the rest of the values.  If, in the course of the evaluation, a
     non-local jump from the FORM is atempted, SI:ERROR-SET traps the
     jump and returns the corresponding jump tag as its value.

 - Function: COMPILED-FUNCTION-NAME (COMPILED-FUNCTION-OBJECT)
     Package:SI

     GCL specific: Returns the name of the COMPILED-FUNCTION-OBJECT.

 - Function: STRUCTUREP (OBJECT)
     Package:SI

     GCL specific: Returns T if the OBJECT is a structure; NIL
     otherwise.

 - Function: IHS-VS (I)
     Package:SI

     GCL specific: Returns the value stack index of the i-th entity in
     the invocation history stack.

 - Function: UNIVERSAL-ERROR-HANDLER (ERROR-NAME CORRECTABLE
          FUNCTION-NAME
     continue-format-string error-format-string        &rest args)
     Package:SI

     GCL specific: Starts the error handler of GCL.  When an error is
     detected, GCL calls SI:UNIVERSAL-ERROR-HANDLER with the specified
     arguments.  ERROR-NAME is the name of the error.  CORRECTABLE is T
     for a correctable error and NIL for a fatal error.  FUNCTION-NAME
     is the name of the function that caused the error.
     CONTINUE-FORMAT-STRING and ERROR-FORMAT-STRING are the format
     strings of the error message.  ARGS are the arguments to the
     format strings.       To change the error handler of GCL, redefine
     SI:UNIVERSAL-ERROR- HANDLER.

 - Variable: *INTERRUPT-ENABLE*
     Package:SI GCL specific: If the value of SI:*INTERRUPT-ENABLE* is
     non-NIL, GCL signals an error on the terminal interrupt (this is
     the default case).  If it is NIL, GCL ignores the interrupt and
     assigns T to SI:*INTERRUPT-ENABLE*.

 - Function: CHDIR (PATHNAME)
     Package:SI

     GCL/UNIX specific: Changes the current working directory to the
     specified pathname.

 - Function: COPY-STREAM (IN-STREAM OUT-STREAM)
     Package:SI

     GCL specific: Copies IN-STREAM to OUT-STREAM until the end-of-file
     on IN- STREAM.

 - Function: INIT-SYSTEM ()
     Package:SI

     GCL specific: Initializes the library and the compiler of GCL.
     Since they have already been initialized in the standard image of
     GCL, calling SI:INIT- SYSTEM will cause an error.

 - Variable: *INDENT-FORMATTED-OUTPUT*
     Package:SI GCL specific: The FORMAT directive ~% indents the next
     line if the value of this variable is non-NIL.  If NIL, ~% simply
     does Newline.

 - Function: SET-HOLE-SIZE (FIXNUM)
     Package:SI

     GCL specific: Sets the size of the memory hole (in pages).

 - Function: FRS-BDS (I)
     Package:SI

     GCL specific: Returns the bind stack index of the i-th entity in
     the frame stack.

 - Function: IHS-FUN (I)
     Package:SI

     GCL specific: Returns the function value of the i-th entity in the
     invocation history stack.

 - Function: *MAKE-CONSTANT (SYMBOL VALUE)
     Package:SI

     GCL specific: Makes the SYMBOL a constant with the specified VALUE.

 - Function: FIXNUMP (OBJECT)
     Package:SI

     GCL specific: Returns T if the OBJECT is a fixnum; NIL otherwise.

 - Function: BDS-VAL (I)
     Package:SI

     GCL specific: Returns the value of the i-th entity in the bind
     stack.

 - Function: STRING-TO-OBJECT (STRING)
     Package:SI

     GCL specific: (SI:STRING-TO-OBJECT STRING) is equivalent to
     (READ-FROM-STRING STRING), but much faster.

 - Variable: *SYSTEM-DIRECTORY*
     Package:SI GCL specific: Holds the name of the system directory of
     GCL.

 - Function: FRS-IHS (I)
     Package:SI

     GCL specific: Returns the invocation history stack index of the
     i-th entity in the frame stack.

 - Function: RESET-GBC-COUNT ()
     Package:SI

     GCL specific: Resets the counter of the garbage collector that
     records how many times the garbage collector has been called for
     each implementation type.

 - Function: CATCH-BAD-SIGNALS ()
     Package:SI

     GCL/BSD specific: Installs a signal catcher for bad signals:
     SIGILL, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS.  The signal
     catcher, upon catching the signal, signals an error (and enter the
     break-level).  Since the internal memory of GCL may be broken, the
     user should check the signal and exit from GCL if necessary.  When
     the signal is caught during garbage collection, GCL terminates
     immediately.

 - Function: RESET-STACK-LIMITS ()
     Package:SI

     GCL specific: Resets the stack limits to the normal state.  When a
     stack has overflowed, GCL extends the limit for the stack in order
     to execute the error handler.  After processing the error, GCL
     resets the stack limit by calling SI:RESET-STACK-LIMITS.

 - Variable: *GBC-MESSAGE*
     Package:SI GCL specific: If the value of SI:*GBC-MESSAGE* is
     non-NIL, the garbage collector prints some information on the
     terminal.  Usually SI:*GBC-MESSAGE* should be set NIL.

 - Variable: *GBC-NOTIFY*
     Package:SI GCL specific: If the value is non-NIL, the garbage
     collector prints a very brief one line message about the area
     causing the collection, and the time spent in internal time units.

 - Variable: *AFTER-GBC-HOOK*
     Package:SI Defaults to nil, but may be set to a function of one
     argument TYPE which is a lisp variable indicating the TYPE which
     caused the current collection.

 - Funcition: ALLOCATED (TYPE)
     Package:SI

     Returns 6 values:
    nfree
          number free

    npages
          number of pages

    maxpage
          number of pages to grow to

    nppage
          number per page

    gbccount
          number of gc's due to running out of items of this size

    nused
          number of items used

     Note that all items of the same size are stored on similar pages.
     Thus for example on a 486 under linux the following basic types are
     all the same size and so will share the same allocated information:
     CONS BIGNUM RATIO COMPLEX STRUCTURE.

 - Function: *MAKE-SPECIAL (SYMBOL)
     Package:SI

     GCL specific: Makes the SYMBOL globally special.

 - Function: MAKE-STRING-OUTPUT-STREAM-FROM-STRING (STRING)
     Package:SI

     GCL specific: Creates a string-output-stream corresponding to the
     STRING and returns it.  The STRING should have a fill-pointer.

 - Variable: *IGNORE-EOF-ON-TERMINAL-IO*
     Package:SI GCL specific: If the value of
     SI:*IGNORE-EOF-ON-TERMINAL-IO* is non-NIL, GCL ignores the
     eof-character (usually ^D) on the terminal and the terminal never
     becomes end-of-file.  The default value of
     SI:*IGNORE-EOF-ON-TERMINAL-IO* is NIL.

 - Function: ADDRESS (OBJECT)
     Package:SI

     GCL specific: Returns the address of the OBJECT as a fixnum.  The
     address of an object depends on the version of GCL.  E.g.
     (SI:ADDRESS NIL) returns 1879062044 on GCL/AOSVS dated March 14,
     1986.

 - Variable: *LISP-MAXPAGES*
     Package:SI GCL specific: Holds the maximum number of pages (1 page
     = 2048 bytes) for the GCL process.  The result of changing the
     value of SI:*LISP-MAXPAGES* is unpredictable.

 - Function: ARGC ()
     Package:SI

     GCL specific: Returns the number of arguments on the command line
     that invoked the GCL process.

 - Function: NANI (FIXNUM)
     Package:SI

     GCL specific: Returns the object in the address FIXNUM.  This
     function is the inverse of SI:ADDRESS.  Although SI:ADDRESS is a
     harmless operation, SI:NANI is quite dangerous and should be used
     with care.

 - Variable: *NOTIFY-GBC*
     Package:SI GCL specific: If the value of this variable is non-NIL,
     then the garbage collector notifies that it begins to run whenever
     it is invoked.  Otherwise, garbage collection begins silently.

 - Function: SAVE-SYSTEM (PATHNAME)
     Package:SI

     GCL specific: Saves the current GCL core imange into a program
     file specified by PATHNAME.  This function differs from SAVE in
     that the contiguous and relocatable areas are made permanent in
     the saved image.  Usually the standard image of GCL
     interpreter/compiler is saved by SI:SAVE-SYSTEM.  This function
     causes an exit from lisp.  Various changes are made to the memory
     of the running system, such as closing files and resetting io
     streams.   It would not be possible to continue normally.

 - Function: UNCATCH-BAD-SIGNALS ()
     Package:SI

     GCL/BSD specific: Undoes the effect of SI:CATCH-BAD-SIGNALS.

 - Function: VS (I)
     Package:SI

     GCL specific: Returns the i-th entity in the value stack.

 - Function: DISPLACED-ARRAY-P (ARRAY)
     Package:SI

     GCL specific: Returns T if the ARRAY is a displaced array; NIL
     otherwise.

 - Function: ARGV (FIXNUM)
     Package:SI

     GCL specific: Returns the FIXNUM-th argument on the command line
     that invoked the GCL process.

 - Variable: *DEFAULT-TIME-ZONE*
     Package:SI GCL specific: Holds the default time zone.  The initial
     value of SI:*DEFAULT- TIME-ZONE* is 6 (the time zone of Austin,
     Texas).

 - Function: GETENV (STRING)
     Package:SI

     GCL/UNIX specific: Returns the environment with the name STRING as
     a string; if the environment specified by STRING is not found,
     returns NIL.

 - Function: FASLINK (FILE STRING)
     Package:SI

     GCL/BSD specific: Loads the FASL file FILE while linking the
     object files and libraries specified by STRING.  For example,
     (faslink "foo.o" "bar.o boo.o -lpixrect") loads foo.o while
     linking two object files (bar.o and boo.o) and the library
     pixrect.  Usually, foo.o consists of the C language interface for
     the functions defined in the object files or the libraries.

     A more portable way of making references to C code, is to build it
     in at the time of the original make.   If foo.c references things
     in -lpixrect, and foo.o is its compilation in the gcl/unixport
     directory

     (cd gcl/unixport ; make "EXTRAS= foo.o -lpixrect ")

     should add them.   If EXTRAS was already joe.o in the
     unixport/makefile you should of course add joe.o to the above
     "EXTRAS= joe.o foo.o.."

     Faslink does not work on most UNIX systems which are derived from
     SYS V or AIX.

 - Function: TOP-LEVEL ()
     Package:SI

     GCL specific: Starts the standard top-level listner of GCL.  When
     the GCL process is invoked, it calls SI:TOP-LEVEL by (FUNCALL
     'SI:TOP-LEVEL).       To change the top-level of GCL, redefine
     SI:TOP-LEVEL and save the core imange in a file.  When the saved
     imange is invoked, it will start the redefined top-level.

 - Function: FRS-VS (I)
     Package:SI

     GCL specific: Returns the value stack index of the i-th entity in
     the frame stack.

 - Function: WRITE-DEBUG-SYMBOLS (START FILE
     &key (main-file "/usr/local/schelter/xgcl/unixport/raw_gcl")
     (output-file "debug-symbols.o" )) Package:SI

     Write out a file of debug-symbols using address START as the place
     where FILE will be loaded into the running executable MAIN-FILE.
     The last is a keyword argument.

 - Function: PROF (X Y)
     Package:SI

     These functions in the SI package are GCL specific, and allow
     monitoring the run time of functions loaded into GCL, as well as
     the basic functions.   Sample Usage:     (si::set-up-profile
     1000000) (si::prof 0 90)      run program     (si::prof 0 0)   ;;
     turn off profile     (si::display-prof)     (si::clear-profile)
     (si::prof 0 90)  ;; start profile again     run program    ..
     Profile can be stopped with (si::prof 0 0) and restarted with
     (si::prof 0 90) The START-ADDRESS will correspond to the beginning
     of the profile array, and the SCALE will mean that 256 bytes of
     code correspond to SCALE bytes in the profile array.

     Thus if the profile array is 1,000,000  bytes long and the code
     segment is 5 megabytes long you can profile the whole thing using
     a scale of 50 Note that long runs may result in overflow, and so
     an understating of the time in a function.

     You must run intensively however since, with a scale of 128 it
     takes 6,000,000 times through a loop to overflow the sampling in
     one part of the code.

 - Function: CATCH-FATAL (I)
     Package:SI

     Sets the value of the C variable catch_fatal to I which should be
     an integer.  If catch_fatal is 1, then most unrecoverable fatal
     errors will be caught.  Upon catching such an error catch_fatal
     becomes -1, to avoid recursive errors.  The top level loop
     automatically sets catch_fatal to 1, if the value is less than
     zero.  Catching can be turned off by making catch_fatal = 0.

 - Variable: *MULTIPLY-STACKS*
     Package:SI

     If this variable is set to a positive fixnum, then the next time
     through the TOP-LEVEL loop, the loop will be exited.  The size of
     the stacks will be multiplied by the value of *multiply-stacks*,
     and the TOP-LEVEL will be called again.  Thus to double the size
     of the stacks:

     >(setq si::*multiply-stacks* 2) [exits top level and reinvokes it,
     with the new stacks in place] >

     We must exit TOP-LEVEL, because it and any other lisp functions
     maintain many pointers into the stacks, which would be incorrect
     when the stacks have been moved.    Interrupting the process of
     growing the stacks, can leave you in an inconsistent state.

 - Function: GBC-TIME (&optional X)
     Package:SI

     Sets the internal C variable gc_time to X if X is supplied and then
     returns gc_time.  If gc_time is greater or equal to 0, then
     gc_time is incremented by the garbage collector, according to the
     number of internal time units spent there.   The initial value of
     gc_time is -1.

 - Function: FWRITE (STRING START COUNT STREAM)
     Package:SI

     Write from STRING starting at char START (or 0 if it is nil) COUNT
     characters (or to end if COUNT is nil) to STREAM.  STREAM must be
     a stream such as returned by FP-OUTPUT-STREAM.  Returns nil if it
     fails.

 - Function: FREAD (STRING START COUNT STREAM)
     Package:SI

     Read characters into STRING starting at char START (or 0 if it is
     nil) COUNT characters (or from start to length of STRING if COUNT
     is nil).  Characters are read from STREAM.  STREAM must be a
     stream such as returned by FP-INPUT-STREAM.  Returns nil if it
     fails.  Return number of characters read if it succeeds.

 - Function: SGC-ON (&optional ON)
     Package:SI

     If ON is not nil then SGC (stratified garbage collection) is turned
     on.   If ON is supplied and is nil, then SGC is turned off.  If ON
     is not supplied, then it returns T if SGC is on, and NIL if SGC is
     off.

     The purpose of SGC is to prevent paging activity during garbage
     collection.  It is efficient if the actual number of pages being
     written to form a small percentage of the total image size.  The
     image should be built as compactly as possible.  This can be
     accomplished by using a settings such as (si::allocate-growth
     'cons 1 10 50 20) to limit the growth in the cons maxpage to 10
     pages per time.    Then just before calling si::save-system to
     save your image you can do something like:

     (si::set-hole-size 500)(gbc nil) (si::sgc-on t) (si::save-system
     ..)

     This makes the saved image come up with SGC on.  We have set a
     reasonably large hole size.  This is so that allocation of pages
     either because they fill up, or through specific calls to
     si::allocate, will not need to move all the relocatable data.
     Moving relocatable data requires turning SGC off, performing a
     full gc, and then turning it back on.  New relocatable data is
     collected by SGC, but moving the old requires going through all
     pages of memory to change pointers into it.

     Using si::*notify-gbc* gives information about the number of pages
     used by SGC.

     Note that SGC is only available on operating systems which provide
     the mprotect system call, to write protect pages.   Otherwise we
     cannot tell which pages have been written too.

 - Function: ALLOCATE-SGC (TYPE MIN-PAGES MAX-PAGES PERCENT-FREE)
     Package:SI

     If MIN-PAGES is 0, then this type will not be swept by SGC.
     Otherwise this is the minimum number of pages to make available to
     SGC.   MAX-PAGES is the upper limit of such pages.   Only pages
     with PERCENT-FREE objects on them, will be assigned to SGC.  A
     list of the previous values for min, max and percent are returned.

 - Function: ALLOCATE-GROWTH (TYPE MIN MAX PERCENT PERCENT-FREE)
     Package:SI

     The next time after a garbage collection for TYPE, if PERCENT-FREE
     of the objects of this TYPE are not actually free, and if the
     maximum number of pages for this type has already been allocated,
     then the maximum number will be increased by PERCENT of the old
     maximum, subject to the condition that this increment be at least
     MIN pages and at most MAX pages.  A list of the previous values
     for min, max, percent, and percent-free for the type TYPE is
     returned.   A value of 0 means use the system default,  and if an
     argument is out of range then the current values are returned with
     no change made.

     Examples: (si::allocate-growth 'cons 1 10 50 10) would insist that
     after a garbage collection for cons, there be at least 10% cons's
     free.   If not the number of cons pages would be grown by 50% or
     10 pages which ever was smaller.   This might be reasonable if you
     were trying to build an image which was `full', ie had few free
     objects of this type.

     (si::allocate-growth 'fixnum 0 10000 30 40) would grow space till
     there were normally 40% free fixnums, usually growing by 30% per
     time.

     (si::allocate-growth 'cons 0 0 0 40) would require 40% free conses
     after garbage collection for conses, and would use system defaults
     for the the rate to grow towards this goal.

     (si::allocate-growth 'cons -1 0 0 0) would return the current
     values, but not make any changes.

 - Function: OPEN-FASD (STREAM DIRECTION EOF-VALUE TABLE)
     Package:SI

     Given file STREAM open for input or output in DIRECTION, set it up
     to start writing or reading in fasd format.   When reading from
     this stream the EOF-VALUE will be returned when the end a fasd end
     of dump marker is encountered.   TABLE should be an eq hashtable
     on output, a vector on input, or nil.   In this last case a
     default one will be constructed.

     We shall refer to the result as a `fasd stream'.   It is suitable
     as the arg to CLOSE-FASD, READ-FASD-TOP, and as the second second
     arg to WRITE-FASD.   As a lisp object it is actually a vector,
     whose body coincides with:

     struct fasd {   object stream;   /* lisp object of type stream */
     object table;  /* hash table used in dumping or vector on input*/
      object eof;      /* lisp object to be returned on coming to eof
     mark */   object direction;    /* holds Cnil or Kinput or Koutput
     */   object package;  /* the package symbols are in by default */
     object index;     /* integer.  The current_dump index on write  */
      object filepos;   /* nil or the position of the start */
     object table_length; /*    On read it is set to the size dump
     array needed 		     or 0 		     */   object macro ; }

     We did not use a defstruct for this, because we want the compiler
     to use this and it makes bootstrapping more difficult.   It is in
     "cmpnew/fasdmacros.lsp"

 - Function: WRITE-FASD-TOP (X FASD-STREAM)
     Package:SI

     Write X to FASD-STREAM.

 - Function: READ-FASD-TOP (FASD-STREAM)
     Package:SI

     Read the next object from FASD-STREAM.   Return the eof-value of
     FASD-STREAM if we encounter an eof marker put out by CLOSE-FASD.
     Encountering end of actual file stream causes an error.

 - Function: CLOSE-FASD (FASD-STREAM)
     Package:SI

     On output write an eof marker to the associated file stream, and
     then make FASD-STREAM invalid for further output.   It also
     attempts to write information to the stream on the size of the
     index table needed to read from the stream from the last open.
     This is useful in growing the array.  It does not alter the file
     stream, other than for writing this information to it.  The file
     stream may be reopened for further use.   It is an error to
     OPEN-FASD the same file or file stream again with out first
     calling CLOSE-FASD.

 - Function: FIND-SHARING-TOP (X TABLE)
     Package:SI

     X is any lisp object and TABLE is an eq hash table.  This walks
     through X making entries to indicate the frequency of
     symbols,lists, and arrays.  Initially items get -1 when they are
     first met, and this is decremented by 1 each time the object
     occurs.  Call this function on all the objects in a fasd file,
     which you wish to share structure.

 - Variable: *LOAD-PATHNAME*
     Package:SI Load binds this to the pathname of the file being
     loaded.

 - Macro: DEFINE-INLINE-FUNCTION (FNAME VARS &body BODY)
     Package:SI

     This is equivalent to defun except that VARS may not contain
     &optional, &rest, &key or &aux.   Also a compiler property is
     added, which essentially saves the body and turns this into a let
     of the VARS and then execution of the body.   This last is done
     using si::DEFINE-COMPILER-MACRO Example:
     (si::define-inline-function myplus (a b c) (+ a b c))

 - Macro: DEFINE-COMPILER-MACRO (FNAME VARS &body BODY)
     Package:SI

     FNAME may be the name of a function, but at compile time the macro
     expansion given by this is used.

     (si::define-compiler-macro mycar (a) `(car ,a))

 - Function: DBL ()
     Package:SI

     Invoke a top level loop, in which debug commands may be entered.
     These commands may also be entered at breaks, or in the error
     handler.  See SOURCE-LEVEL-DEBUG

 - Function: NLOAD (FILE)
     Package:SI

     Load a file with the readtable bound to a special readtable, which
     permits tracking of source line information as the file is loaded.
     see SOURCE-LEVEL-DEBUG

 - Function: BREAK-FUNCTION (FUNCTION &optional LINE ABSOLUTE)
     Package:SI

     Set a breakpoint for a FUNCTION at LINE if the function has source
     information loaded.  If ABSOLUTE is not nil, then the line is
     understood to be relative to the beginning of the buffer.  See
     also dbl-break-function, the emacs command.

 - Function: XDR-OPEN (STREAM)
     Package:SI

     Returns an object suitable for passing to XDR-READ if the stream
     is an input stream, and XDR-WRITE if it was an output stream.
     Note the stream must be a unix stream, on which
     si::fp-input-stream or si::fp-output-stream would act as the
     identity.

 - Function: FP-INPUT-STREAM (STREAM)
     Package:SI

     Return a unix stream for input associated to STREAM if possible,
     otherwise return nil.

 - Function: FP-OUTPUT-STREAM (STREAM)
     Package:SI

     Return a unix stream for output associated to STREAM if possible,
     otherwise return nil.

 - Function: XDR-READ (STREAM ELEMENT)
     Package:SI

     Read one item from STREAM of type the type of ELEMENT.    The
     representation of the elements is machine independent.    The xdr
     routines are what is used by the basic unix rpc calls.

 - Function: XDR-WRITE (STREAM ELEMENT)
     Package:SI

     Write to STREAM the given ELEMENT.

 - Variable: *TOP-LEVEL-HOOK*
     Package:SI If this variable is has a function as its value at
     start up time, then it is run immediately after the init.lsp file
     is loaded.    This is useful for starting up an alternate top
     level loop.

 - Function: MULTIPLY-BIGNUM-STACK (N)
     Package:SI

     Increase the internal bignum stack by a factor of N.  Normally
     space on this stack is recovered after each complete lisp
     expression is evaluated.  However if you are dealing with large
     integers, you may need to use this function to increase the stack.

 - Function: RUN-PROCESS (STRING ARGLIST)
     Package:SI

     Execute the command STRING in a subshell passing the strings in the
     list ARGLIST as arguments to the command.  Return a two way stream
     associated to this.  Use si::fp-output-stream to get an associated
     output stream or si::fp-input-stream.

     Bugs: It does not properly deallocate everything, so that it will
     fail if you call it too many times.

 - Function: STRING-MATCH (PATTERN STRING &optional START END)
     Package: SI Match regexp PATTERN in STRING starting in string
     starting at START and ending at END.  Return -1 if match not
     found, otherwise return the start index  of the first matchs.  The
     variable *MATCH-DATA* will be set to a fixnum array of sufficient
     size to hold the matches, to be obtained with match-beginning and
     match-end.  If it already contains such an array, then the
     contents of it will be over written.

     The form of a regexp pattern is discussed in Regular Expressions.

 - Function: MATCH-BEGINNING (INDEX)
     Returns the beginning of the I'th match from the previous
     STRING-MATCH, where the 0th is for the whole regexp and the
     subsequent ones match parenthetical expressions.  -1 is returned
     if there is no match, or if the *match-data* vector is not a
     fixnum array.

 - Function: MATCH-END (INDEX)
     Returns the end of the I'th match from the previous STRING-MATCH

Regular Expressions
-------------------

   The function `string-match' (*Index string-match::) is used to match
a regular expression against a string.  If the variable
`*case-fold-search*' is not nil, case is ignored in the match.  To
determine the extent of the match use *Index match-beginning:: and
*Index match-end::.

   Regular expressions are implemented using Henry Spencer's package
(thank you  Henry!), and much of the description of regular expressions
below is copied verbatim from his manual entry.  Code for delimited
searches, case insensitive searches, and speedups to allow fast
searching of long files was contributed by W. Schelter.  The speedups
use an adaptation by Schelter of the Boyer and Moore string search
algorithm to the case of branched regular expressions.  These allow
such expressions as 'not_there|really_not' to be searched for 30 times
faster than in GNU emacs (1995), and 200 times faster than in the
original Spencer method.  Expressions such as [a-u]bcdex get a speedup
of 60 and 194 times respectively.  This is based on searching a string
of 50000 characters (such as the file tk.lisp).

   * A regular expression is a string containing zero or more branches
     which are separated by `|'.  A match of the regular expression
     against a string is simply a match of the string with one of the
     branches.

   * Each branch consists of zero or more pieces, concatenated.   A
     matching string must contain an initial substring  matching the
     first piece, immediately followed by a second substring matching
     the second piece and so on.

   * Each piece is an atom optionally followed by  `+', `*', or `?'.

   * An atom followed by `+' matches a sequence of 1 or more matches of
     the atom.

   * An atom followed by `*' matches a sequence of 0 or more matches of
     the atom.

   * An atom followed by `?' matches a match of the atom, or the null
     string.

   * An atom is
        - a regular expression in parentheses matching a match for the
          regular expression

        - a range see below

        - a `.' matching any single character

        - a `^' matching the null string at the beginning of the input
          string

        - a `$' matching the null string at the end of the input string

        - a `\' followed by a single character matching that character

        - a single character with no other significance (matching that
          character).

   * A range is a sequence of characters enclosed in `[]'.  It normally
     matches any single character from the sequence.
        - If the sequence begins with `^', it matches any single
          character not from the rest of the sequence.

        - If two characters in the sequence are separated by `-', this
          is shorthand for the full list of ASCII characters between
          them (e.g. `[0-9]' matches any decimal digit).

        - To include a literal `]' in the sequence, make it the first
          character (following a possible `^').

        - To include a literal `-', make it the first or last character.

Ordering Multiple Matches
-------------------------

   In general there may be more than one way to match a regular
expression to an input string.  For example, consider the command

      (string-match "(a*)b*"  "aabaaabb")

   Considering only the rules given so far, the value of (list-matches
0 1) might be `("aabb" "aa")' or `("aaab" "aaa")' or `("ab" "a")' or
any of several other combinations.  To resolve this potential ambiguity
string-match chooses among alternatives using the rule first then
longest.  In other words, it considers the possible matches in order
working from left to right across the input string and the pattern, and
it attempts to match longer pieces of the input string before shorter
ones.  More specifically, the following rules apply in decreasing order
of priority:
     [1] If a regular expression could match two different parts of an
     input string then it will match the one that begins earliest.

     [2] If a regular expression contains | operators then the leftmost
     matching sub-expression is chosen.

     [3] In *, +, and ? constructs, longer matches are chosen in
     preference to shorter ones.

     [4] In sequences of expression components the components are
     considered from left to right.

   In the example from above, (a*)b* matches aab:  the (a*) portion of
the pattern is matched first and it consumes the leading aa; then the
b* portion of the pattern consumes the next b.  Or, consider the
following example:

      (string-match "(ab|a)(b*)c"  "xabc") ==> 1
      (list-matches 0 1 2 3) ==> ("abc" "ab" "" NIL)
      (match-beginning 0) ==> 1
      (match-end 0) ==> 4
      (match-beginning 1) ==> 1
      (match-end 1) ==> 3
      (match-beginning 2) ==> 3
      (match-end 2) ==> 3
      (match-beginning 3) ==> -1
      (match-end 3) ==> -1

   In the above example the return value of `1' (which is `> -1')
indicates that a match was found.   The entire match runs from 1 to 4.
Rule 4 specifies that (ab|a) gets first shot at the input string and
Rule 2 specifies that the ab sub-expression is checked before the a
sub-expression.  Thus the b has already been claimed before the (b*)
component is checked and (b*) must match an empty string.

   The special characters in the string `"\()[]+.*|^$?"', must be
quoted, if a simple string search is desired.   The function
re-quote-string is provided for this purpose.
     (re-quote-string "*standard*") ==> "\\*standard\\*"

     (string-match (re-quote-string "*standard*") "X *standard* ")
      ==> 2

     (string-match "*standard*" "X *standard* ")
     Error: Regexp Error: ?+* follows nothing
   Note there is actually just one `\' before the `*' but the printer
makes two so that the string can be read, since `\' is also the lisp
quote character.   In the last example an error is signalled since the
special character `*' must follow an atom if it is interpreted as a
regular expression.

Debugging
*********

Source Level Debugging in Emacs
===============================

   In emacs load (load "dbl.el") from the gcl/doc directory.  [ It also
requires gcl.el from that directory.    Your system administrator
should do make in the doc directory, so that these files are copied to
the standard location.]

   OVERVIEW:

   Lisp files loaded with si::nload will have source line information
about them recorded.  Break points may be set, and functions stepped.
Source code will be automatically displayed in the other window, with a
little arrow beside the current line.  The backtrace (command :bt) will
show line information and you will get automatic display of the source
as you move up and down the stack.

   FUNCTIONS: break points which have been set.     si::nload (file)
  load a lisp file collecting source line information.

   si::break-function (function &optional line absolute)      set up a
breakpoint for FUNCTION at LINE relative to start or ABSOLUTE

   EMACS COMMANDS: M-x dbl makes a dbl buffer, suitable for running an
inferior gcl.  It has special keybindings for stepping and viewing
sources.   You may start your favorite gcl program in the dbl shell
buffer.

   Inferior Dbl Mode: Major mode for interacting with an inferior Dbl
process.  The following commands are available:

   C-c l           dbl-find-line

   ESC d           dbl-:down ESC u           dbl-:up ESC c
dbl-:r ESC n           dbl-:next ESC i           dbl-:step ESC s
  dbl-:step

   M-x dbl-display-frame displays in the other window the last line
referred to in the dbl buffer.

   ESC i and ESC n in the dbl window, call dbl to step and next and
then update the other window with the current file and position.

   If you are in a source file, you may select a point to break at, by
doing C-x SPC.

   Commands: Many commands are inherited from shell mode.  Additionally
we have:

   M-x dbl-display-frame display frames file in other window ESC i
advance one line in program ESC n advance one line in program (skip
over calls).  M-x send-dbl-command used for special printing of an arg
at the current point.  C-x SPACE sets break point at current line.

   ---------------------------

   When visiting a lisp buffer (if gcl.el is loaded in your emacs) the
command c-m-x evaluates the current defun into the process running in
the other window.  Line information will be kept.  This line
information allows you to set break points at a given line (by typing
C-x \space on the line in the source file where you want the break to
occur.  Once stopped within a function you may single step with M-s.
This moves one line at a time in the source code, displaying a little
arrow beside your current position.  M-c is like M-s, except that
function invocations are skipped over, rather than entered into.  M-c
continues execution.

   Keywords typed at top level, in the debug loop have a special
meaning:
   * :delete  [n1] [n2] .. - delete all break points or just n1,n2

   * :disable [n1] [n2] .. - disable all break points or just n1,n2

   * :enable  [n1] [n2] .. - enable all break points or just n1,n2

   * :info  [:bkpt]      -print information about

   * :break [fun] [line] - break at the current location, or if
     fun is supplied in fun.   Break  at the beginning unless a
     line offset from the beginning of fun is supplied.

   * :fr [n] go to frame n   When in frame n, if the frame is
     interpreted,     typing the name of locals, will print their
     values.   If it is compiled     you must use (si::loc j) to print
     `locj'.   Autodisplay of the source     will take place if it is
     interpreted and the line can be determined.

   * :up [n] go up n frames from the current frame.

   * :down [n] go down n frames

   * :bt [n] back trace starting at the current frame and going to top
     level      If n is specified show only n frames.

   * :r  If stopped in a function resume.   If at top level in the dbl
      loop, exit and resume an outer loop.

   * :q  quit the computation back to top level dbl loop.

   * :step step to the next line with line information

   * :next  step to the next line with line information skipping over
     function     invocations.

   Files:  debug.lsp  dbl.el    gcl.el

Low Level Debug Functions
=========================

   Use the following functions to directly access GCL stacks.
     (SI:VS i)	Returns the i-th entity in VS.
     (SI:IHS-VS i)	Returns the VS index of the i-th entity in IHS.
     (SI:IHS-FUN i)	Returns the function of the i-th entity in IHS.
     (SI:FRS-VS i)	Returns the VS index of the i-th entity in FRS.
     (SI:FRS-BDS i)	Returns the BDS index of the i-th entity in FRS.
     (SI:FRS-IHS i)	Returns the IHS index of the i-th entity in FRS.
     (SI:BDS-VAR i)	Returns the symbol of the i-th entity in BDS.
     (SI:BDS-VAL i)	Returns the value of the i-th entity in BDS.

     (SI:SUPER-GO i tag)
     	Jumps to the specified tag established by the TAGBODY frame at
     	FRS[i].  Both arguments are evaluated.  If FRS[i] happens to be
     	a non-TAGBODY frame, then (THROW (SI:IHS-TAG i) (VALUES)) is
     	performed.

Miscellaneous
*************

Environment
===========

   The environment in GCL which is passed to macroexpand and other
functions requesting an environment, should be a list of 3 lists.
The first list looks like ((v1 val1) (v2 val2) ..) where vi are
variables and vali are their values.  The second is a list of ((fname1
. fbody1) (fname2 . fbody2) ...) where fbody1 is either (macro
lambda-list lambda-body) or (lambda-list lambda-body) depending on
whether this is a macro or a function.   The third list contains tags
and blocks.

Initialization
==============

   If the file init.lsp exists in the current directory, it is loaded
at startup.  The first argument passed to the executable image should
be the system directory.  Normally this would be gcl/unixport.  This
directory is stored in the si::*system-directory* variable.  If the
file sys-init.lsp exists in the system directory, it is loaded before
init.lsp.  See also si::*TOP-LEVEL-HOOK*.

Low Level X Interface
=====================

   A sample program for drawing things on X windows from lisp is
included in the file gcl/lsp/littleXlsp.lsp

   That routine invokes the corresponding C routines in XLIB.  So in
order to use it you must `faslink' in the X routines.  Directions are
given at the beginning of the lisp file, for either building them into
the image or using faslink.

   This program is also a good tutorial on invoking C from lisp.

   See also defentry and faslink.

Compiler Definitions
********************

 - Function: EMIT-FN (TURN-ON)
     Package:COMPILER

     If TURN-ON is t, the subsequent calls to  COMPILE-FILE will cause
     compilation of foo.lisp to emit a foo.fn as well as foo.o.  The
     .fn file contains cross referencing information as well as
     information useful to the collection utilities in cmpnew/collectfn
     This latter file must be manually loaded to call emit-fn.

 - Variable: *CMPINCLUDE-STRING*
     Package:COMPILER If it is a string it holds the text of the
     cmpinclude.h file appropriate for this version.  Otherwise the
     usual #include of *cmpinclude* will be used.  To disable this
     feature set *cmpinclude-string* to NIL in the init-form.

 - Function: EMIT-FN (TURN-ON)
     Package:COMPILER

     If TURN-ON is t, then subsequent calls to compile-file on a file
     foo.lisp cause output of a file foo.fn.  This .fn file contains
     lisp structures describing the functions in foo.lisp.  Some tools
     for analyzing this data base are WHO-CALLS,
     LIST-UNDEFINED-FUNCTIONS, LIST-UNCALLED-FUNCTIONS, and
     MAKE-PROCLAIMS.

     Usage: (compiler::emit-fn t) (compile-file "foo1.lisp")
     (compile-file "foo2.lisp")

     This would create foo1.fn and foo2.fn.  These may be loaded using
     LOAD.  Each time compile-file is called the data base is cleared.
     Immediately after the compilation, the data base consists of data
     from the compilation.  Thus if you wished to find functions called
     but not defined in the current file, you could do
     (list-undefined-functions), immediately following the compilation.
     If you have a large system, you would load all the .fn files
     before using the above tools.

 - Function: MAKE-ALL-PROCLAIMS (&rest DIRECTORIES)
     Package:COMPILER

     For each D in DIRECTORIES all files in (directory D) are loaded.

     For example (make-all-proclaims "lsp/*.fn" "cmpnew/*.fn") would
     load any files in lsp/*.fn and cmpnew/*.fn.

     [See EMIT-FN for details on creation of .fn files]

     Then calculations on the newly loaded .fn files are made, to
     determine function proclamations.  If number of values of a
     function cannot be determined [for example because of a final
     funcall, or call of a function totally unknown at this time] then
     return type * is assigned.

     Finally a file sys-proclaim.lisp is written out.  This file
     contains function proclamations.

     (load "sys-proclaim.lisp") (compile-file "foo1.lisp")
     (compile-file "foo2.lisp")

 - Function: MAKE-PROCLAIMS (&optional (STREAM *STANDARD-OUTPUT*))
     Package:COMPILER

     Write to STREAM the function proclaims from the current data base.
     Usually a number of .fn files are loaded prior to running this.
     See EMIT-FN for details on how to collect this.  Simply use LOAD
     to load in .fn files.

 - Function: LIST-UNDEFINED-FUNCTIONS ()
     Package:COMPILER

     Return a list of all functions called but not defined, in the
     current data base (see EMIT-FN).

          Sample:
          (compiler::emit-fn t)
          (compile-file "foo1.lisp")
          (compiler::list-undefined-functions)
          or
          (mapcar 'load (directory "*.fn")) (compiler::list-undefined-functions)

 - Function: WHO-CALLS (FUNCTION-NAME)
     Package:COMPILER

     List all functions in the data base [see emit-fn] which call
     FUNCTION-NAME.

 - Function: LIST-UNCALLED-FUNCTIONS ()
     Package:COMPILER

     Examine the current data base [see emit-fn] for any functions or
     macros which are called but are not: fboundp, OR defined in the
     data base, OR having special compiler optimizer properties which
     would eliminate an actual call.

 - Variable: *CC*
     Package:COMPILER Has value a string which controls which C
     compiler is used by GCL.  Usually this string is obtained from the
     machine.defs file, but may be reset by the user, to change
     compilers or add an include path.

 - Variable: *SPLIT-FILES*
     Package:COMPILER This affects the behaviour of compile-file, and
     is useful for cases where the C compiler cannot handle large C
     files resulting from lisp compilation.  This scheme should allow
     arbitrarily long lisp files to be compiled.

     If the  value [default NIL] is a positive integer, then the source
     file will be compiled into several object files whose names have
     0,1,2,.. prepended, and which will be loaded by the main object
     file.     File 0 will contain compilation of top level forms thru
     position *split-files* in the lisp source file, and file 1 the
     next forms, etc.   Thus a 180k file would probably result in three
     object files (plus the master object file of the same name) if
     *split-files* was set to 60000.  The package information will be
     inserted in each file.

 - Variable: *COMPILE-ORDINARIES*
     Package:COMPILER If this has a non nil value [default = nil], then
     all top level forms will be compiled into machine instructions.
     Otherwise only defun's, defmacro's, and top level forms beginning
     with (progn 'compile ...) will do so.