   This is a Texinfo GCL SYSTEM INTERNALS Manual

   Copyright 1994 William F. Schelter

Operating System Definitions
============================

 - Function: GET-DECODED-TIME ()
     Package:LISP

     Returns the current time in decoded time format.  Returns nine
     values: second, minute, hour, date, month, year, day-of-week,
     daylight-saving-time-p, and time-zone.

 - Function: HOST-NAMESTRING (PATHNAME)
     Package:LISP

     Returns the host part of PATHNAME as a string.

 - Function: RENAME-FILE (FILE NEW-NAME)
     Package:LISP

     Renames the file FILE to NEW-NAME.  FILE may be a string, a
     pathname, or a stream.

 - Function: FILE-AUTHOR (FILE)
     Package:LISP

     Returns the author name of the specified file, as a string.  FILE
     may be a string or a stream

 - Function: PATHNAME-HOST (PATHNAME)
     Package:LISP

     Returns the host slot of PATHNAME.

 - Function: FILE-POSITION (FILE-STREAM &optional POSITION)
     Package:LISP

     Sets the file pointer of the specified file to POSITION, if
     POSITION is given.  Otherwise, returns the current file position
     of the specified file.

 - Function: DECODE-UNIVERSAL-TIME (UNIVERSAL-TIME &optional (TIMEZONE
          -9))
     Package:LISP

     Converts UNIVERSAL-TIME into a decoded time at the TIMEZONE.
     Returns nine values: second, minute, hour, date, month (1 - 12),
     year, day-of-week (0 - 6), daylight-saving-time-p, and time-zone.
     TIMEZONE in GCL defaults to 6, the time zone of Austin, Texas.

 - Function: USER-HOMEDIR-PATHNAME (&optional HOST)
     Package:LISP

     Returns the home directory of the logged in user as a pathname.
     HOST is ignored.

 - Variable: *MODULES*
     Package:LISP A list of names of the modules that have been loaded
     into GCL.

 - Function: SHORT-SITE-NAME ()
     Package:LISP

     Returns a string that identifies the physical location of the
     current GCL.

 - Function: DIRECTORY (NAME)
     Package:LISP

     Returns a list of files that match NAME.  NAME may be a string, a
     pathname, or a file stream.

 - Function: SOFTWARE-VERSION ()
     Package:LISP

     Returns a string that identifies the software version of the
     software under which GCL is currently running.

 - Constant: INTERNAL-TIME-UNITS-PER-SECOND
     Package:LISP The number of internal time units that fit into a
     second.

 - Function: ENOUGH-NAMESTRING (PATHNAME &optional (DEFAULTS
          *DEFAULT-PATHNAME-DEFAULTS*))
     Package:LISP

     Returns a string which uniquely identifies PATHNAME with respect to
     DEFAULTS.

 - Function: REQUIRE (MODULE-NAME &optional (PATHNAME))
     Package:LISP

     If the specified module is not present, then loads the appropriate
     file(s).  PATHNAME may be a single pathname or it may be a list of
     pathnames.

 - Function: ENCODE-UNIVERSAL-TIME (SECOND MINUTE HOUR DATE MONTH YEAR
          &optional (TIMEZONE ))
     Package:LISP

     Does the inverse operation of DECODE-UNIVERSAL-TIME.

 - Function: LISP-IMPLEMENTATION-VERSION ()
     Package:LISP

     Returns a string that tells you when the current GCL
     implementation is brought up.

 - Function: MACHINE-INSTANCE ()
     Package:LISP

     Returns a string that identifies the machine instance of the
     machine on which GCL is currently running.

 - Function: ROOM (&optional (X T))
     Package:LISP

     Displays information about storage allocation in the following
     format.

        * for each type class
             * the number of pages so-far allocated for the type class

             * the maximum number of pages for the type class

             * the percentage of used cells to cells so-far allocated

             * the number of times the garbage collector has been
               called to 	  collect cells of the type class

             * the implementation types that belongs to the type class

        * the number of pages actually allocated for contiguous blocks

        * the maximum number of pages for contiguous blocks

        * the number of times the garbage collector has been called to
          collect   contiguous blocks

        * the number of pages in the hole

        * the maximum number of pages for relocatable blocks

        * the number of times the garbage collector has been called to
          collect   relocatable blocks

        * the total number of pages allocated for cells

        * the total number of pages allocated

        * the number of available pages

        * the number of pages GCL can use.

          The number of times the garbage collector has been called is
          not shown, if the number is zero.  The optional X is ignored.

 - Function: GET-UNIVERSAL-TIME ()
     Package:LISP

     Returns the current time as a single integer in universal time
     format.

 - Function: GET-INTERNAL-RUN-TIME ()
     Package:LISP

     Returns the run time in the internal time format.  This is useful
     for finding CPU usage.  If the operating system allows, a second
     value containing CPU usage of child processes is returned.

 - Variable: *DEFAULT-PATHNAME-DEFAULTS*
     Package:LISP The default pathname-defaults pathname.

 - Function: LONG-SITE-NAME ()
     Package:LISP

     Returns a string that identifies the physical location of the
     current GCL.

 - Function: DELETE-FILE (FILE)
     Package:LISP  Deletes FILE.

 - Function: GET-INTERNAL-REAL-TIME ()
     Package:LISP

     Returns the real time in the internal time format.  This is useful
     for finding elapsed time.

 - Function: MACHINE-TYPE ()
     Package:LISP

     Returns a string that identifies the machine type of the machine
     on which GCL is currently running.

 - Macro: TIME
     Package:LISP

     Syntax:
          (time form)

     Evaluates FORM and outputs timing statistics on *TRACE-OUTPUT*.

 - Function: SOFTWARE-TYPE ()
     Package:LISP

     Returns a string that identifies the software type of the software
     under which GCL is currently running.

 - Function: LISP-IMPLEMENTATION-TYPE ()
     Package:LISP

     Returns a string that tells you that you are using a version of
     GCL.

 - Function: SLEEP (N)
     Package:LISP

     This function causes execution to be suspended for N seconds.  N
     may be any non-negative, non-complex number.

Structures
**********

 - Macro: DEFSTRUCT
     Package:LISP

     Syntax:
          (defstruct
                   {name | (name {:conc-name | (:conc-name prefix-string) |
                                  :constructor | (:constructor symbol [lambda-list]) |
                                  :copier | (:copier symbol) |
                                  :predicate | (:predicate symbol) |
                                  (:include symbol) |
                                  (:print-function function) |
                                  (:type {vector | (vector type) | list}) |
                                  :named | (:static { nil | t})
                                  (:initial-offset number)}*)}
                   [doc]
                   {slot-name |
                    (slot-name [default-value-form] {:type type | :read-only flag}*) }*
                   )

     Defines a structure.  The doc-string DOC, if supplied, is saved as
     a STRUCTURE doc and can be retrieved by (documentation 'NAME
     'structure).  STATIC is gcl specific and makes the body non
     relocatable.

     See the files misc/rusage.lsp misc/cstruct.lsp, for examples of
     making a lisp structure correspond to a C structure.

 - Function: HELP (&optional SYMBOL)
     Package:LISP

     GCL specific: Prints the documentation associated with SYMBOL.
     With no argument, this function prints the greeting message to GCL
     beginners.

Iteration and Tests
*******************

 - Macro: DO-EXTERNAL-SYMBOLS
     Package:LISP

     Syntax:
          (do-external-symbols (var [package [result-form]])
                    {decl}* {tag | statement}*)

     Executes STATEMENTs once for each external symbol in the PACKAGE
     (which defaults to the current package), with VAR bound to the
     current symbol.  Then evaluates RESULT-FORM (which defaults to
     NIL) and returns the value(s).

 - Special Form: DO*
     Package:LISP

     Syntax:
          (do* ({(var [init [step]])}*) (endtest {result}*)
                    {decl}* {tag | statement}*)

     Just like DO, but performs variable bindings and assignments in
     serial, just like LET* and SETQ do.

 - Macro: DO-ALL-SYMBOLS
     Package:LISP

     Syntax:
          (do-all-symbols (var [result-form]) {decl}* {tag | statement}*)

     Executes STATEMENTs once for each symbol in each package, with VAR
     bound to the current symbol.  Then evaluates RESULT-FORM (which
     defaults to NIL) and returns the value(s).

 - Function: YES-OR-NO-P (&optional (FORMAT-STRING NIL) &rest ARGS)
     Package:LISP

     Asks the user a question whose answer is either 'YES' or 'NO'.  If
     FORMAT- STRING is non-NIL, then FRESH-LINE operation is performed,
     a message is printed as if FORMAT-STRING and ARGs were given to
     FORMAT, and then a prompt "(Yes or No)" is printed.  Otherwise, no
     prompt will appear.

 - Function: MAPHASH #'HASH-TABLE
     Package:LISP

     For each entry in HASH-TABLE, calls FUNCTION on the key and value
     of the entry; returns NIL.

 - Function: MAPCAR (FUN LIST &rest MORE-LISTS)
     Package:LISP

     Applies FUN to successive cars of LISTs and returns the results as
     a list.

 - Special Form: DOLIST
     Package:LISP

     Syntax:
          (dolist (var listform [result]) {decl}* {tag | statement}*)

     Executes STATEMENTs, with VAR bound to each member of the list
     value of LISTFORM.  Then returns the value(s) of RESULT (which
     defaults to NIL).

 - Function: EQ (X Y)
     Package:LISP

     Returns T if X and Y are the same identical object; NIL otherwise.

 - Function: EQUALP (X Y)
     Package:LISP

     Returns T if X and Y are EQUAL, if they are characters and satisfy
     CHAR-EQUAL, if they are numbers and have the same numerical value,
     or if they have components that are all EQUALP.  Returns NIL
     otherwise.

 - Function: EQUAL (X Y)
     Package:LISP

     Returns T if X and Y are EQL or if they are of the same type and
     corresponding components are EQUAL.  Returns NIL otherwise.
     Strings and bit-vectors are EQUAL if they are the same length and
     have identical components.  Other arrays must be EQ to be EQUAL.

 - Macro: DO-SYMBOLS
     Package:LISP

     Syntax:
          (do-symbols (var [package [result-form]]) {decl}* {tag |
          statement}*)

     Executes STATEMENTs once for each symbol in the PACKAGE (which
     defaults to the current package), with VAR bound to the current
     symbol.  Then evaluates RESULT-FORM (which defaults to NIL) and
     returns the value(s).

 - Special Form: LOOP
     Package:LISP

     Syntax:
          (loop {form}*)

     Executes FORMs repeatedly until exited by a THROW or RETURN.  The
     FORMs are surrounded by an implicit NIL block.

User Interface
**************

 - Special Variable: -
     Package:LISP Holds the top-level form that GCL is currently
     evaluating.

 - Function: - (NUMBER &rest MORE-NUMBERS)
     Package:LISP

     Subtracts the second and all subsequent NUMBERs from the first
     NUMBER.  With one arg, negates it.

 - Macro: UNTRACE
     Package:LISP

     Syntax:
          (untrace {function-name}*)

     Removes tracing from the specified functions.  With no
     FUNCTION-NAMEs, untraces all functions.

 - Variable: ***
     Package:LISP Gets the previous value of ** when GCL evaluates a
     top-level form.

 - Function: MAKE-STRING-INPUT-STREAM (STRING &optional (START 0) (END
          (LENGTH STRING)))
     Package:LISP

     Returns an input stream which will supply the characters of String
     between Start and End in order.

 - Macro: STEP
     Package:LISP

     Syntax:
          (step form)

     Evaluates FORM in the single-step mode and returns the value.

 - Variable: *BREAK-ENABLE*
     Package:LISP GCL specific:  When an error occurrs, control enters
     to the break loop only if the value of this variable is non-NIL.

 - Special Variable: /
     Package:LISP Holds a list of the values of the last top-level form.

 - Function: DESCRIBE (X)
     Package:LISP

     Prints a description of the object X.

 - Function: ED (&optional X)
     Package:LISP

     Invokes the editor.  The action depends on the version of GCL.

 - Variable: *DEBUG-IO*
     Package:LISP Holds the I/O stream used by the GCL debugger.

 - Variable: *BREAK-ON-WARNINGS*
     Package:LISP When the function WARN is called, control enters to
     the break loop only if the value of this varialbe is non-NIL.

 - Function: CERROR (CONTINUE-FORMAT-STRING ERROR-FORMAT-STRING &rest
          ARGS)
     Package:LISP

     Signals a correctable error.

 - Variable: **
     Package:LISP Gets the previous value of * when GCL evaluates a
     top-level form.

 - Special Variable: +++
     Package:LISP Gets the previous value of ++ when GCL evaluates a
     top-level form.

 - Function: INSPECT (X)
     Package:LISP

     Shows the information about the object X in an interactive manner

 - Special Variable: //
     Package:LISP Gets the previous value of / when GCL evaluates a
     top-level form.

 - Variable: *TRACE-OUTPUT*
     Package:LISP The trace output stream.

 - Special Variable: ++
     Package:LISP Gets the previous value of + when GCL evaluates a
     top-level form.

 - Variable: *ERROR-OUTPUT*
     Package:LISP Holds the output stream for error messages.

 - Function: DRIBBLE (&optional PATHNAME)
     Package:LISP

     If PATHNAME is given, begins to record the interaction to the
     specified file.  If PATHNAME is not given, ends the recording.

 - Variable: *
     Package:LISP Holds the value of the last top-level form.

 - Special Variable: ///
     Package:LISP Gets the previous value of // when GCL evaluates a
     top-level form.

 - Function: WARN (FORMAT-STRING &rest ARGS)
     Package:LISP

     Formats FORMAT-STRING and ARGs to *ERROR-OUTPUT* as a warning
     message.

 - Function: BREAK (&optional (FORMAT-STRING NIL) &rest ARGS)
     Package:LISP

     Enters a break loop.  If FORMAT-STRING is non-NIL, formats
     FORMAT-STRING and ARGS to *ERROR-OUTPUT* before entering a break
     loop.  Typing :HELP at the break loop will list the break-loop
     commands.

 - Special Variable: +
     Package:LISP Holds the last top-level form.

 - Macro: TRACE
     Package:LISP

     Syntax:
          (trace {function-name}*)

     Traces the specified functions.  With no FUNCTION-NAMEs, returns a
     list of functions currently being traced.

     Additional Keywords are allowed in GCL with the syntax (trace {fn
     | (fn {:kw form}*)}*)

     For each FN naming a function, traces that function.  Each :KW
     should be one of the ones listed below, and FORM should have the
     corresponding form.  No :KW may be given more than once for the
     same FN.  Returns a list of all FNs now traced which weren't
     already traced.

     EXAMPLE (Try this with your favorite factorial function FACT):

          ;; print entry args and exit values

          (trace FACT)

          ;; Break coming out of FACT if the value is bigger than 1000.

          (trace (fact :exit
          	     (progn
          	       (if (> (car values) 1000)(break "big result"))
          	       (car values))))

          ;; Hairy example:

          ;;make arglist available without the si:: prefix
          (import 'si::arglist)

          (trace (fact
                  :DECLARATIONS
                  ((in-string "Here comes input: ")
                   (out-string "Here comes output: ")
                   all-values
                   (silly (+ 3 4)))
                  :COND
                  (equal (rem (car arglist) 2) 0)
                  :ENTRY
                  (progn
                    (cond
                     ((equal (car arglist) 8)
                      (princ "Entering FACT on input 8!! ")
                      (setq out-string "Here comes output from inside (FACT 8): "))
                     (t
                      (princ in-string)))
                    (car arglist))
                  :EXIT
                  (progn
                    (setq all-values (cons (car values) all-values))
                    (princ out-string)
                    (when (equal (car arglist) 8)
                          ;; reset out-string
                          (setq out-string "Here comes output: "))
                    (cons 'fact values))
                  :ENTRYCOND
                  (not (= (car arglist) 6))
                  :EXITCOND
                  (not (= (car values) (* 6 (car arglist))))
                  :DEPTH
                  5))

     Syntax is `:keyword' form1 `:keyword' form2 ...

    `:declarations'
               DEFAULT: NIL

          FORM is ((var1  form1 )(var2  form2 )...), where the var_i
          are symbols distinct from each other and from all symbols
          which are similarly declared for currently traced functions.
          Each form  is evaluated immediately.  Upon any invocation of
          a traced function when not already inside a traced function
          call, each var  is bound to that value of form .

    `:COND'
               DEFAULT: T

          Here, FORM is any Lisp form to be evaluated (by EVAL) upon
          entering a call of FN, in the environment where si::ARGLIST
          is bound to the current list of arguments of FN.  Note that
          even if the evaluation of FORM changes the value of
          SI::ARGLIST (e.g. by evaluation of (SETQ si::ARGLIST ...)),
          the list of arguments passed to FN is unchanged.  Users may
          alter args passed by destructively modifying the list
          structure of SI::ARGLIST however. The call is traced (thus
          invoking the :ENTRYCOND and :EXITCOND forms, at least) if and
          only if FORM does not evaluate to NIL.

    `:ENTRYCOND'
               DEFAULT: T

          This is evaluated (by EVAL) if the :COND form evaluates to
          non-NIL, both in an environment where SI::ARGLIST is bound to
          the current list of arguments of FN.  If non-NIL, the :ENTRY
          form is then evaluated and printed with the trace "prompt".

    `:ENTRY'
               DEFAULT: (CONS (QUOTE x) SI::ARGLIST),

          where x is the symbol we call FN If the :COND and :ENTRYCOND
          forms evaluate to non-NIL, then the trace "prompt" is printed
          and then this FORM is evaluated (by EVAL) in an environment
          where SI::ARGLIST is bound to the current list of arguments
          of FN.  The result is then printed.

    `:EXITCOND'
               DEFAULT: T

          This is evaluated (by EVAL) in the environment described
          below for the :EXIT form.  The :EXIT form is then evaluated
          and printed with the "prompt" if and only if the result here
          is non-NIL.

    `:EXIT'
               DEFAULT: (CONS (QUOTE x) VALUES),

          where x is the symbol we call FN Upon exit from tracing a
          given call, this FORM is evaluated (after the appropriate
          trace "prompt" is printed), using EVAL in an environment
          where SI::ARGLIST is bound to the current list of arguments
          of FN and VALUES is bound to the list of values returned by
          FN (recalling that Common Lisp functions may return multiple
          values).

    `:DEPTH'
               DEFAULT:  No depth limit

          FORM is simply a positive integer specifying the maximum
          nesting of traced calls of FN, i.e. of calls of FN in which
          the :COND form evaluated to non-NIL.  For calls of FN in
          which this limit is exceeded, even the :COND form is not
          evaluated, and the call is not traced.

Doc
***

 - Function: APROPOS (STRING &optional (PACKAGE NIL))
     Package:LISP

     Prints those symbols whose print-names contain STRING as substring.
     If PACKAGE is non-NIL, then only the specified package is searched.

 - Function: INFO (STRING &optional (LIST-OF-INFO-FILES
          *DEFAULT-INFO-FILES*))
     PACKAGE:SI

     Find all documentation about STRING in LIST-OF-INFO-FILES.  The
     search is done for STRING as a substring of a node name, or for
     STRING in the indexed entries in the first index for each info
     file.  Typically that should be a variable and function definition
     index, if the info file is about a programming language.  If the
     windowing system is connected, then a choice box is offered and
     double clicking on an item brings up its documentation.

     Otherwise a list of choices is offered and the user may select
     some of these choices.

     list-of-info-files is of the form
           ("gcl-si.info" "gcl-tk.info" "gcl.info")
     The above list is the default value of *default-info-files*, a
     variable in the SI package.   To find these files in the file
     system, the search path *info-paths* is consulted as is the master
     info directory `dir'.

     see *Index *default-info-files*:: and *Index *info-paths*::.  For
     example
          (info "defun")

           0: DEFUN :(gcl-si.info)Special Forms and Functions.
           1: (gcl.info)defun.
          Enter n, all, none, or multiple choices eg 1 3 : 1

          Info from file /home/wfs/gcl-doc/gcl.info:
          defun                                                               [Macro]
          ---------------------------------------------------------------------------
          `Defun'  function-name lambda-list [[{declaration}* | documentation]]
          ...
     would list the node `(gcl.info)defun'.  That is the node entitled
     `defun' from the info file gcl.info.   That documentation is based
     on the ANSI common lisp standard.   The choice
          DEFUN :(gcl-si.info)Special Forms and Functions.

     refers to the documentation on DEFUN from the info file
     gcl-si.info in the node Special Forms And Functions.  This is an
     index reference and only the part of the node which refers to
     `defun' will be printed.

          (info "factor" '("maxima.info"))
     would search the maxima info files index and nodes for `factor'.

 - Variable: *info-paths*
     Package SI:

     A list of strings such as
            '("" "/usr/info/" "/usr/local/lib/info/" "/usr/local/info/"
              "/usr/local/gnu/info/" )
     saying where to look for the info files.   It is used implicitly
     by `info', see *Index info::.

     Looking for maxima.info would look for the file maxima.info in all
     the directories listed in *info-paths*.  If nto found then it
     would look for `dir' in the *info-paths* directories, and if it
     were found it would look in the `dir' for a menu item such as

          * maxima: (/home/wfs/maxima-5.0/info/maxima.info).

     If such an entry exists then the directory there would be used for
     the purpose of finding `maxima.info'

Type
****

 - Function: COERCE (X TYPE)
     Package:LISP

     Coerces X to an object of the type TYPE.

 - Function: TYPE-OF (X)
     Package:LISP

     Returns the type of X.

 - Function: CONSTANTP (SYMBOL)
     Package:LISP

     Returns T if the variable named by SYMBOL is a constant; NIL
     otherwise.

 - Function: TYPEP (X TYPE)
     Package:LISP

     Returns T if X is of the type TYPE; NIL otherwise.

 - Function: COMMONP (X)
     Package:LISP

     Returns T if X is a Common Lisp object; NIL otherwise.

 - Function: SUBTYPEP (TYPE1 TYPE2)
     Package:LISP

     Returns T if TYPE1 is a subtype of TYPE2; NIL otherwise.  If it
     could not determine, then returns NIL as the second value.
     Otherwise, the second value is T.

 - Macro: CHECK-TYPE
     Package:LISP

     Syntax:
          (check-type place typespec [string])

     Signals an error, if the contents of PLACE are not of the
     specified type.

 - Macro: ASSERT
     Package:LISP

     Syntax:
          (assert test-form [({place}*) [string {arg}*]])

     Signals an error if the value of TEST-FORM is NIL.  STRING is an
     format string used as the error message.  ARGs are arguments to
     the format string.

 - Macro: DEFTYPE
     Package:LISP

     Syntax:
          (deftype name lambda-list {decl | doc}* {form}*)

     Defines a new type-specifier abbreviation in terms of an
     'expansion' function 	(lambda lambda-list1 {decl}* {form}*)
     where lambda-list1 is identical to LAMBDA-LIST except that all
     optional parameters with no default value specified in LAMBDA-LIST
     defaults to the symbol '*', but not to NIL.  When the type system
     of GCL encounters a type specifier (NAME arg1 ... argn), it calls
     the expansion function with the arguments arg1 ... argn, and uses
     the returned value instead of the original type specifier.  When
     the symbol NAME is used as a type specifier, the expansion
     function is called with no argument.  The doc-string DOC, if
     supplied, is saved as the TYPE doc of NAME, and is retrieved by
     (documentation 'NAME 'type).

 - Declaration: DYNAMIC-EXTENT
     Package:LISP Declaration to allow locals to be cons'd on the C
     stack.  For example (defun foo (&rest l) (declare (:dynamic-extent
     l)) ...) will cause l to be a list formed on the C stack of the
     foo function frame.  Of course passing L out as a value of foo
     will cause havoc.  (setq x (make-list n)) (setq x (cons a b))
     (setq x (list a  b c ..)) also are handled on the stack, for
     dynamic-extent x.

GCL Specific
************

 - Function: SYSTEM (STRING)
     Package:LISP

     GCL specific: Executes a Shell command as if STRING is an input to
     the Shell.  Not all versions of GCL support this function.

 - Variable: *IGNORE-MAXIMUM-PAGES*
     Package:LISP GCL specific: Tells the GCL memory manager whether
     (non-NIL) or not (NIL) it should expand memory whenever the
     maximum allocatable pages have been used up.

 - Function: MACHINE-VERSION ()
     Package:LISP

     Returns a string that identifies the machine version of the machine
     on which GCL is currently running.

 - Function: BY ()
     Package:LISP

     GCL specific: Exits from GCL.

 - Macro: DEFCFUN
     Package:LISP

     Syntax:
          (defcfun header n {element}*)

     GCL specific: Defines a C-language function which calls Lisp
     functions and/or handles Lisp objects.  HEADER gives the header of
     the C function as a string.  Non-negative-integer is the number of
     the main stack entries used by the C function, primarily for
     protecting Lisp objects from being garbage-collected.  Each
     ELEMENT may give a C code fragment as a string, or it may be a list
     ((symbol {arg}*) {place}*) which, when executed, calls the Lisp
     function named by SYMBOL with the specified arguments and saves
     the value(s) to the specified places.  The DEFCFUN form has the
     above meanings only after compiled;  The GCL interpreter simply
     ignores this form.

     An example which defines a C function list2 of two arguments, but
     which calls the 'lisp' function CONS by name, and refers to the
     constant 'NIL.

     (defCfun "object list2(x,y) object x,y;" 0               "object
     z;"                ('NIL z)                ((CONS y z) z)
          ((CONS x z) z)          	"return(z);" )

     In lisp the operations in the body would be    (setq z 'nil)
     (setq z (cons y z))    (setq z (cons x z))

     Syntax:

                  (defCfun header non-negative-integer
                          { string
                            | ( function-symbol { value }* )
                            | (( function-symbol  { value }* ) { place }* ) })

          value:
          place:
                   { C-expr | ( C-type C-expr ) }

          C-function-name:
          C-expr:
                   { string | symbol }

          C-type:
                   { object | int | char | float | double }

 - Macro: CLINES
     Package:LISP

     Syntax:
          (clines {string}*)

     GCL specific:  The GCL compiler embeds STRINGs into the
     intermediate C language code.  The interpreter ignores this form.

 - Function: ALLOCATE (TYPE NUMBER &optional (REALLY-ALLOCATE NIL))
     Package:LISP

     GCL specific: Sets the maximum number of pages for the type class
     of the GCL implementation type TYPE to NUMBER.  If REALLY-ALLOCATE
     is given a non-NIL value, then the specified number of pages will
     be allocated immediately.

 - Function: GBC (X)
     Package:LISP

     GCL specific: Invokes the garbage collector (GC) with the
     collection level specified by X.  NIL as the argument causes GC to
     collect cells only.  T as the argument causes GC to collect
     everything.

 - Function: SAVE (PATHNAME)
     Package:LISP

     GCL specific: Saves the current GCL core image into a program file
     specified by PATHNAME.  This function depends on the version of
     GCL.  The function si::save-system is to be preferred in almost
     all circumstances.   Unlike save, it makes the relocatable section
     permanent, and causes no future gc of currently loaded .o files.

 - Function: HELP* (STRING &optional (PACKAGE 'LISP))
     Package:LISP

     GCL specific: Prints the documentation associated with those
     symbols in the specified package whose print names contain STRING
     as substring.  STRING may be a symbol, in which case the
     print-name of that symbol is used.  If PACKAGE is NIL, then all
     packages are searched.

 - Macro: DEFLA
     Package:LISP

     Syntax:
          (defla name lambda-list {decl | doc}* {form}*)

     GCL specific: Used to DEFine Lisp Alternative.  For the
     interpreter, DEFLA is equivalent to DEFUN, but the compiler
     ignores this form.

 - Function: PROCLAMATION (DECL-SPEC)
     Package:LISP

     GCL specific: Returns T if the specified declaration is globally
     in effect; NIL otherwise.  See the doc of DECLARE for possible
     DECL-SPECs.

 - Macro: DEFENTRY
     Package:LISP

     Syntax:
          (defentry name arg-types c-function)

     GCL specific: The compiler defines a Lisp function whose body
     consists of a calling sequence to the C language function
     specified by C-FUNCTION.  The interpreter ignores this form.  The
     ARG-TYPES specifies the C types of the arguments which C-FUNCTION
     requires.  The list of allowed types is (object char int float
     double string).  Code will be produced to coerce from a lisp
     object to the appropriate type before passing the argument to the
     C-FUNCTION.  The c-function should be of the form (c-result-type
     c-fname) where c-result-type is a member of (void object char int
     float double string).  c-fname may be a symbol (in which case it
     will be downcased) or a string.  If c-function is not a list, then
     (object c-function) is assumed.

            Sample usage:
          --File begin-----
          ;; JOE takes X a lisp string and Y a fixnum and returns a character.
          (clines "#include \"foo.ch\"")
          (defentry joe (string int) (char "our_c_fun"))
          ---File end------
          ---File foo.ch---
          /* C function for extracting the i'th element of a string */
          static char our_c_fun(p,i)
          char *p;
          int i;
             {
          	return p[i];
             }
          -----File end---

     One must be careful of storage allocation issues when passing a
     string.  If the C code invokes storage allocation (either by
     calling `malloc' or `make_cons' etc), then there is a possibility
     of a garbage collection, so that if the string passed was not
     constructed with `:static t' when its array was constructed, then
     it could move.  If the C function may allocate storage, then you
     should pass a copy:
          (defun safe-c-string (x)
            (let* ((n (length x))
                   (a (make-array (+ n 1) :element-type 'string-char
                     :static t :fill-pointer n)))
              (si::copy-array-portion x y 0 0 n)
              (setf (aref a n) (code-char 0)))
              a)

 - Function: COPY-ARRAY-PORTION (X,Y,I1,I2,N1)
     Package:SI Copy elements from X to Y starting at X[i1] to Y[i2]
     and doing N1 elements if N1 is supplied otherwise, doing the
     length of X - I1 elements.  If the types of the arrays are not the
     same, this has implementation dependent results.

 - Function: BYE ()
     Package:LISP

     GCL specific: Exits from GCL.

 - Function: USE-FAST-LINKS (TURN-ON)
     Package:LISP

     GCL specific: If TURN-ON is not nil, the fast link mechanism is
     enabled, so that ordinary function calls will not appear in the
     invocation stack, and calls will be much faster.  This is the
     default.   If you anticipate needing to see a stack trace in the
     debugger, then you should turn this off.

Bignums
=======

   A directory mp was added to hold the new multi precision arithmetic
code.  The layout and a fair amount of code in the mp directory is an
enhanced version of gpari version 34. The gpari c code was rewritten to
be more efficient, and gcc assembler macros were added to allow
inlining of operations not possible to do in C.  On a 68K machine, this
allows the C version to be as efficient as the very carefully written
assembler in the gpari distribution.  For the main machines, an
assembler file (produced by gcc) based on this new method, is included.
 This is for sites which do not have gcc, or do not wish to compile
the whole system with gcc.

   Bignum arithmetic is much faster now.  Many changes were made to
cmpnew also, to add 'integer' as a new type.  It differs from variables
of other types, in that storage is associated to each such variable,
and assignments mean copying the storage.  This allows a function which
does a good deal of bignum arithmetic, to do very little consing in the
heap.  An example is the computation of PI-INV in scratchpad, which
calculates the inverse of pi to a prescribed number of bits accuracy.
That function is now about 20 times faster, and no longer causes
garbage collection.  In versions of GCL  where HAVE_ALLOCA is defined,
the temporary storage growth is on the C stack, although this often not
so critical (for example it makes virtually no difference in the PI-INV
example, since in spite of the many operations, only one storage
allocation takes place.

   Below is the actual code for PI-INV

   On a sun3/280 (cli.com)

   Here is the comparison of lucid and gcl before and after on that
pi-inv.   Times are in seconds with multiples of the gcl/akcl time in
parentheses.

   On a sun3/280 (cli.com)

     pi-inv   akcl-566  franz        lucid         old kcl/akcl
     ----------------------------------------
     10000      3.3     9.2(2.8 X)  15.3 (4.6X)    92.7   (29.5 X)
     20000      12.7    31.0(2.4 X) 62.2 (4.9X)    580.0  (45.5 X)

     (defun pi-inv (bits &aux (m 0))
       (declare (integer bits m))
       (let* ((n (+ bits (integer-length bits) 11))
              (tt (truncate (ash 1 n) 882))
              (d (* 4 882 882))
              (s 0))
         (declare (integer s d tt n))
         (do ((i 2 (+ i 2))
              (j 1123 (+ j 21460)))
             ((zerop tt) (cons s (- (+ n 2))))
           (declare (integer i j))
             (setq s (+ s (* j tt))
                   m (- (* (- i 1) (- (* 2 i) 1) (- (* 2 i) 3)))
                   tt (truncate (* m tt) (* d (the integer (expt i 3))))))))

C Interface
***********

Available Symbols
=================

   When GCL is built, those symbols in the system libraries which are
referenced by functions linked in in the list of objects given in
`unixport/makefile', become available for reference by GCL code.

   On some systems it is possible with `faslink' to load `.o' files
which reference other libraries, but in general this practice is not
portable.