CHICKEN

A practical and portable Scheme system - User's manual

(Version 0, Build 990)


Copyright (c) 2000-2002, Felix L. Winkelmann
All rights reserved.

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

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


Table of contents:

  1. Introduction
  2. Using the compiler
    1. Command line format
    2. Runtime options
    3. An example
    4. Extending the compiler
    5. Distributing compiled C files
  3. Using the interpreter
    1. Command line format
    2. Writing Scheme scripts
    3. Toplevel commands
    4. Macros and procedures implemented in the interpreter
    5. Extending the interpreter
  4. Supported language
    1. Deviations from the standard
    2. Extensions to the standard
    3. Non standard read syntax
    4. Non-standard macros and special forms
      1. Binding forms for optional arguments
      2. Other binding forms
      3. Substitution forms and macros
      4. Conditional forms
      5. Record structures
      6. Other forms
    5. Declarations
    6. Interface to external functions and variables
      1. Accessing external objects
      2. Foreign type specifiers
      3. Entry points
      4. Callbacks
    7. Parameters
    8. The module system
    9. Unit: library
      1. Arithmetic
      2. Input/Output
      3. Files
      4. String ports
      5. Feature identifiers
      6. Keywords
      7. Exceptions
      8. Miscellaneous
    10. Unit: eval
      1. Expressions
      2. Read-eval-print loop
      3. Macros
      4. Miscellaneous
    11. Unit: debugger
    12. Unit: extras
      1. Lists
      2. String-port extensions
      3. Formatted output
      4. Hash tables
      5. Queues
      6. Sorting
      7. Random numbers
      8. Input/Output extensions
      9. Strings
      10. Miscellaneous
    13. Unit: srfi-1
    14. Unit: srfi-4
    15. Unit: srfi-13
    16. Unit: srfi-14
    17. Unit: match
    18. Unit: regex
    19. Unit: syntax-case
    20. Unit: srfi-18
    21. Unit: format
    22. Unit: unistd
      1. Pathname operations
      2. Directories
      3. File descriptors and low-level I/O
      4. Retrieving file attributes
      5. Pipes
      6. Fifos
      7. Processes
      8. Symbolic links
      9. Permissions, owners, users and groups
      10. Record locking
      11. Signal handling
      12. Environment access
      13. Memory mapped I/O
      14. Time routines
      15. Miscellanous routines
      16. How Scheme procedures relate to UNIX C functions
    23. Unit: lolevel
      1. Foreign pointers
      2. Serialization
      3. Extending procedures with data
      4. Byte-Vectors
      5. Miscellanous routines
    24. Unit: tinyclos
      1. Defining forms
      2. Base language
      3. Introspectiion
      4. Intercessory protocol
      5. Additional protocol
      6. Utility procedures
      7. Builtin classes
    25. Additional files
      1. describe.scm
      2. process.scm
      3. records.scm
      4. report.scm
  5. Data representation
  6. Implementation notes
  7. Bugs and limitations
  8. Acknowledgements
  9. References

  1. Introduction
  2. CHICKEN is a compiler that translates Scheme source-files into C, which in turn can be fed to a C-compiler to generate a standalone executable. This principle, which is used by several existing compilers, achieves high portability because C is implemented on nearly all available platforms.

    This package is distributed under a BSD license and as such is free to use and modify. An interpreter is also available and can be used as a scripting environment or for testing programs before compilation.

    The method of compilation and the design of the runtime-system follow closely Henry Baker's "Cheney on the MTA" [1] paper and expose a number of interesting properties: consing (creation of data on the heap) is relatively inexpensive, because a generational garbage collection scheme is used, in which short-lived data structures are reclaimed extremely quickly. Furthermore, call-with-current-continuation is practically for free and CHICKEN does not suffer under any performance penalties if first-class continuations are used in complex ways. The generated C code is fully tail-recursive.

    Some of the features supported by CHICKEN:


  3. Using the compiler
  4. The compiler translates Scheme source-code into fairly portable C source-code that can be compiled and linked with most available C compilers. The interface to CHICKEN is intentionally simple. System dependent makefiles, shell-scripts or batch-files should perform any necessary steps before and after invocation of CHICKEN. On UNIX-compatible systems, a shell script named chicken-config is supplied that emits the correct options for the host system's C compiler (enter "chicken-config -help" on the command line for a list of available options).

    1. Command line format
    2. chicken FILENAME {OPTION}

      FILENAME is the complete pathname of the source-file that is to be translated into C. A filename argument of "-" specifies that the source text should be read from standard input. Possible options are:

      -benchmark-mode
      Equivalent to -optimize-level 3 -fixnum-arithmetic -disable-interrupts -block.
      -block
      Enable block-compilation. When this option is specified, the compiler assumes that global variables are not modified outside this compilation-unit. Specifically, toplevel bindings are not seen by eval and unused toplevel bindings are removed.
      -case-sensitive
      Enables the reader to read symbols case sensitive. The default is to read non case sensitive. This option registers the case-sensitive feature identifier.
      -check-syntax
      Aborts compilation process after macro-expansion and syntax checks.
      -database-size NUMBER
      Specifies the initial size of the analysis-database. Should only be used if extremely large files are to be compiled.
      -debug MODES
      Enables one or more compiler debugging modes. MODES is a string of characters that select debugging information about the compiler that will be printed to standard output.

      t show time and memory needed
      b show breakdown of time needed for each compiler pass
      o show performed optimizations
      r show invocation parameters
      s show program-size information and other statistics
      a show node-matching during simplification
      p show execution of compiler sub-passes
      i show potential inlining candidates
      m show GC statistics during compilation
      x display information about experimental features
      1 show source expressions
      2 show canonicalized expressions
      3 show expressions converted into CPS
      4 show database after each analysis pass
      5 show expressions after each optimization pass
      6 show expressions after each inlining pass
      7 show expressions after complete optimization
      8 show database after final analysis
      9 show expressions after closure conversion

      -debug-calls
      Emit extra code to track all procedure invocations that are not calls to do or named let procedures. -debug-calls implies -emit-debug-info.
      -debug-level LEVEL
      Selects amount of debug-information. LEVEL should be an integer.

      • -debug-level 0 is equivalent to -no-trace.
      • -debug-level 1 does nothing.
      • -debug-level 2 is equivalent to -emit-debug-info.
      • -debug-level 3 is equivalent to -emit-debug-info -debug-calls.
      • -debug-level N with N >= 4 is equivalent to -emit-debug-info -debug-calls -debug-loops.
      -debug-loops
      Emits debug-information for all procedures, i.e. do loops and named let. Note that this will turn all tail-recursive loops into non-tail-recursive ones. Implies -debug-calls and -emit-debug-info.
      -dependency-output FILENAME
      Specifies target filename for dependency rule generated by the -write-dependencies option.
      -disable-interrupts
      Equivalent to the (disable-interrupts) declaration. No interrupt-checks are generated for compiled programs.
      -emit-debug-info
      Emits extended debugging information for use with the debugger unit. Note that this option increases code size and execution speed substantially. Moreover the compiler instruments the source code in such ways that any calls in tail position (besides do loops and named let forms) are not tail-calls anymore!
      -epilogue FILENAME
      Includes the file named FILENAME at the end of the compiled source file. The include-path is not searched. This option may be given multiple times.
      -expand-only
      Stops compilation after macro expansion phase and writes canonicalized expressions to output file.
      -explicit-use
      Disables automatic use of the units library and eval. Use this option if compiling a library unit instead of an application unit.
      -extend FILENAME
      Loads a Scheme source file before compilation commences. This feature can be used to extend the compiler. This option may be given multiple times.
      -feature SYMBOL
      Registers SYMBOL to be a valid feature identifier for cond-expand.
      -fixnum-arithmetic
      Equivalent to (fixnum-arithmetic) declaration. Assume all mathematical operations use small integer arguments.
      -heap-size NUMBER
      Sets the static heap size of the generated executable to NUMBER bytes. The parameter may be followed by a M (m) or K (k) suffix which stand for mega- and kilobytes, respectively. The default heap size is 16 megabytes.
      -help
      Print a summary of available options and the format of the command line parameters and exit the compiler.
      -hygienic
      Load syntax-case macro package and enable high-level macros in compiled code. This option registers the hygienic-macros feature identifier.
      -include-path PATHNAME
      Specifies an additional search path for files included via the include special form. This option may be given multiple times. If the environment variable CHICKEN_INCLUDE_PATH is set, it should contain a list of alternative include pathnames separated by ";". The environment variable CHICKEN_HOME is also considered as a search path.
      -inline
      Enable procedure inlining.

      Note: this option, when applied to large source files can result in ridiculously long compile times.

      -inline-limit NUMBER
      Specify maximum growth of original program due to inlining in NUMBER percent (i.e. -inline-limit 100 limits the size of the program to twice its original size). The default inline-limit is 100 percent.
      -inline-passes NUMBER
      Specifies maximal number of inlining passes. The default number is 3.
      -no-trace
      Disable generation of tracing information. If a compiled executable should halt due to a runtime error, then a file containing a stack-trace will be written to the current directory under the name STACKTRACE. Each line in the created file gives the name and the line-number (if available) of a procedure call. With this option given, the generated code is slightly faster.
      -no-fancy-ports
      Identical to the (no-fancy-ports) declaration. All ports are assumed to be file- or stdio- ports.
      -no-feature SYMBOL
      Unregisters feature identifier SYMBOL.
      -no-warnings
      Disable generation of compiler warnings.
      -no-winding-callcc
      Identical to the (no-winding-callcc) declaration. All uses of call-with-current-continuation do not respect dynamic-wind before- and after-thunks.
      -nursery NUMBER
      -stack-size NUMBER
      Sets the size of the first heap-generation of the generated executable to NUMBER bytes. The parameter may be followed by a M (m) or K (k) suffix. The default stack-size depends on the target platform.
      -optimize
      Enables optimizations. This will improve performance of compiled programs, but compile times will be longer.
      -optimize-leaf-routines
      Enable leaf routine optimization.
      -optimize-level LEVEL
      Enables certain sets of optimization options. LEVEL should be an integer.

      • -optimize-level 0 does nothing.
      • -optimize-level 1 is equivalent to -optimize -no-trace -optimize-leaf-routines.
      • -optimize-level 2 is equivalent to -optimize -no-trace -optimize-leaf-routines -usual-integrations.
      • -optimize-level 3 is equivalent to -optimize -no-trace -optimize-leaf-routines -usual-integrations -unsafe.
      • -optimize-level N with N >= 4 is equivalent to -optimize -no-trace -optimize-leaf-routines -usual-integrations -unsafe -inline.
      -output-file FILENAME
      Specifies the pathname of the generated C file. Default is out.c.
      -postlude EXPRESSIONS
      Add EXPRESSIONS after all other toplevel expressions in the compiled file. This option may be given multiple times. Processing of this option takes place after processing of -epilogue.
      -prelude EXPRESSIONS
      Add EXPRESSIONS before all other toplevel expressions in the compiled file. This option may be given multiple times. Processing of this option takes place before processing of -prologue.
      -profile FILENAME
      Instruments the source code to count procedure calls and execution times. After the program terminates (either via an explicit exit or implicitly), profiling statistics are written to FILENAME. Each line of the generated file contains a list with the procedure name, the number of calls and the time spent executing it. Use the script formatprofile to display the profiling information in a more user-friendly form. Enter formatprofile with no arguments at the command line to get a list of available options.
      Note that the file is only important in the compilation of the main compilation unit. For library units the option is still needed (to record procedures defined in that unit), but the filename is ignored.
      -prologue FILENAME
      Includes the file named FILENAME at the start of the compiled source file. The include-path is not searched. This option may be given multiple times.
      -quiet
      Disables output of compile information.
      -srfi-7
      Process the source as a SRFI-7 configuration language file (see: the SRFI-7 document).
      -strict
      Disable non-standard macros. This option registers the strict feature identifier.
      -strict-srfi-0
      Disable non-standard macros except cond-expand. This option registers the strict feature identifier.
      -to-stdout
      Write compiled code to standard output instead of creating a .c file.
      -unsafe
      Disable runtime safety checks.
      -usual-integrations
      Specifies that standard procedures and certain internal procedures are never redefined, and can be inlined. This is equivalent to declaring (usual-integrations).
      -version
      Prints the version and some copyright information and exit the compiler.
      -verbose
      Prints progress information to standard output during compilation.
      -write-dependencies
      Output a rule suitable for make which specify any dependencies of the currently compiled file to included source files. If -dependency-output is not given, the rule is written to standard output. You can specify the -check-syntax option additionally to avoid compilation of the source file.

      The environment variable CHICKEN_OPTIONS can be set to a string with default command-line options for the compiler.

    3. Runtime options
    4. After successful compilation a C source-file is generated and can be compiled with a C compiler. Executables generated with CHICKEN (and the compiler itself) accept a small set of runtime options:

      -:b
      Enter debugger break-loop before execution of main compilation unit commences (but after the toplevel expressions of library units are executed). This works only if the unit was compiled with debug information enabled (-emit-debug-info).
      -:c
      Forces console mode. Currently this is only used in the interpreter (csi) to force output of the >>> prompt even if stdin is not a terminal (for example if running in an emacs buffer under Windows).
      -:d
      Prints some debug-information during startup.
      -:hNUMBER
      Specifies heap size
      -:sNUMBER
      Specifies stack size
      -:tNUMBER
      Specifies symbol-table size
      -:w
      Enables garbage collection of unused symbols. By default unused and unbound symbols are not garbage collected.

      The argument values may be given in bytes, in kilobytes (suffixed with K or k) or in megabytes suffixed with M or m). Runtime options may be combined, like -:bc, but everything following a NUMBER argument is ignored. So -:wh64m is OK, but -:h64mw will not enable GC of unused symbols.

    5. An example
    6. To compile a Scheme program (assuming a UNIX-like environment) we perform the following steps:

      • Consider this Scheme source file, named foo.scm
          ;;; foo.scm
        
          (define (fac n)
            (if (zero? n)
                1
                (* n (fac (- n 1))) ) )
        
          (print (fac 10))
        
      • Compile the file foo.scm
        % chicken foo.scm -output-file foo.c
      • Compile the generated C file foo.c
        % gcc foo.c -o foo `chicken-config -cflags -libs`
      • Start the compiled program
        % foo

      The option -output-file foo.c specifies the name of the C file that is to be generated by CHICKEN. Without this option a file named out.c would be created.

      If multiple Scheme modules are to be combined into a single executable, then we have to compile each module and link the resulting object files together with the runtime system:

      • Consider these two Scheme source files, named foo.scm and bar.scm
          ;;; foo.scm
        
          (declare (uses bar))
        
          (write (fac 10)) (newline)
        
        
          ;;; bar.scm
        
          (declare (unit bar))
        
          (define (fac n)
            (if (zero? n)
                1
                (* n (fac (- n 1))) ) )
        
      • Compile the files foo.scm and bar.scm
        % chicken foo.scm -output-file foo.c
        % chicken bar.scm -output-file bar.c -explicit-use
      • Compile the generated C files foo.c and bar.c
        % gcc -c foo.c `chicken-config -cflags`
        % gcc -c bar.c `chicken-config -cflags`
      • Link the object files foo.o and bar.o
        % gcc foo.o bar.o -o foo `chicken-config -libs`
      • Start the compiled program
        % foo

      The declarations specify which of the compiled files is the main module, and which is the library module. An executable can only have one main module, since a program has only a single entry-point. In this case foo.scm is the main module, because it doesn't have a unit declaration. Library modules should be compiled with the -explicit-use option.

      Extensions to the basic CHICKEN runtime libraries are available in a separate utility library (libstuffed-chicken.a on UNIX-like platforms, chicken-utilities.lib on Windows systems). Whenever you use one or more of the units extras, format, srfi-1, srfi-4, srfi-13, srfi-14, srfi-18, match, unistd, lolevel, tinyclos or regex, then you should add this library to the command line of the C compiler or linker (this is equivalent to adding the -extra-libs option to chicken-config):

        ;;; foo.scm
      
        (declare (uses unistd format))
      
        (format #t "Anno Domini ~@R~%" (+ 1900 (vector-ref (seconds->local-time (current-seconds)) 5))
      
      
        % chicken foo.scm -output-file foo.c
        % gcc foo.c `chicken-config -cflags -extra-libs -libs` -o foo
        % foo
      

    7. Extending the compiler
    8. The compiler supplies a couple of hooks to add user-level passes to the compilation process. Before compilation commences any Scheme source-files specified using the -extend option are loaded and evaluated. The parameters user-options-pass, user-read-pass, user-preprocessor-pass and user-pass can be set to procedures that are called to perform certain compilation passes instead of the usual processing (for more information about parameters see: Parameters).

      [parameter] user-options-pass
      Holds a procedure that will be called with a list of command-line arguments and should return two values: the source-filename and the actual list of options, where compiler switches have their leading - (hyphen) removed and are converted to symbols.
      Note that this parameter is invoked before processing of the -extend option, and so can only be changed in compiled user passes.
      [parameter] user-read-pass
      Holds a procedure of three arguments. The first argument is a list of strings with the code passed to the compiler via -prelude options. The second argument is a list of source files including any files specified by -prologue and -epilogue. The third argument is a list of strings specified using -postlude options. The procedure should return a list of toplevel Scheme expressions.
      [parameter] user-preprocessor-pass
      Holds a procedure of one argument. This procedure is applied to each toplevel expression in the source file before macro-expansion. The result is macro-expanded and compiled in place of the original expression.
      [parameter] user-pass
      Holds a procedure of one argument. This procedure is applied to each toplevel expression after macro-expansion. The result of the procedure is then compiled in place of the original expression.

      Extensions loaded via -extend are interpreted. To add compiled user-passes the compiler has to be rebuild. Loaded code has access to the library units extras, srfi-1, srfi-4 and match. The highlevel macro-system and multithreading is not available.

      Note that the macroexpansion/canonicalization phase of the compiler adds certain forms to the source program. These extra expressions are not seen by user-preprocessor-pass but by user-pass.

      The script file extend-chicken can be used to rebuild the compiler with added library units, much in the same way as extend-csi (see: extending the interpreter ).

    9. Distributing compiled C files

      It is relatively easy to create distributions of Scheme projects that have been compiled to C. The CHICKEN distribution contains a template makefile (called Makefile.d for GCC based systems, or Makefile.d.vc for Windows systems that use Visual C++) that can be adapted to build an executable from translated C sources.
      The runtime system of CHICKEN consists of only two handcoded C files (runtime.c and chicken.h). All other modules of the runtime system and the extension libraries are just compiled Scheme code.

      An example:

      • Consider these two source files:
        ;;; foo.scm
        
        (declare (uses bar))
        
        (say-hello)
        
        and
        ;;; bar.scm
        
        (declare (unit bar) (uses unistd))
        
        (define (say-hello)
          (print "Hello, " (nth-value 0 (user-information (current-user-id)))) )
        
      • Compiling them yields two C files:
        
        % chicken foo.scm -output-file foo.c -quiet
        % chicken bar.scm -output-file bar.c -quiet -explicit-use
        
      • The makefile for generating the executable foo would look like this:
        CC = gcc
        CFLAGS = -I. -O3 -fomit-frame-pointer -fstrict-aliasing
        
        foo : foo.o bar.o libchicken.a libstuffed-chicken.a
                gcc -s -L. foo.o bar.o -o $@ -lchicken -lstuffed-chicken
        foo.o : foo.c chicken.h
        bar.o : bar.c chicken.h
        
        libchicken.a : runtime.o library.o eval.o syntax-case.o
        	ar rus $@ $^
        libstuffed-chicken.a : extras.o format.o srfi-1.o srfi-4.o srfi-13.o srfi-14.o match.o \
                 srfi-18.o lolevel.o regex.o unistd.o
        	ar rus $@ $^
        libembedded-chicken.a : embedded-runtime.o library.o eval.o syntax-case.o
        	ar rus $@ $^
        runtime.o : runtime.c chicken.h
        embedded-runtime.o : runtime.c chicken.h
        	$(CC) $(CFLAGS) -DC_EMBEDDED -c $< -o $@
        eval.o : eval.c chicken.h
        library.o : library.c chicken.h
        modules.o : modules.c chicken.h
        extras.o : extras.c chicken.h
        srfi-1.o : srfi-1.c chicken.h
        srfi-4.o : srfi-4.c chicken.h
        match.o : match.c chicken.h
        syntax-case.o : syntax-case.c chicken.h
        srfi-18.o : srfi-18.c chicken.h
        format.o : format.c chicken.h
        tinyclos.o : tinyclos.c chicken.h
        srfi-13.o : srfi-13.c chicken.h
        srfi-14.o : srfi-14.c chicken.h
        lolevel.o : lolevel.c chicken.h
        regex.o : regex.c chicken.h
        unistd.o : unistd.c chicken.h
        
      • If CHICKEN was properly installed, then the C files needed can be found in the directory $(CHICKEN_HOME)/src (or just take them from the original tar archive).
        Don't forget chicken.h.
      • Some of the libraries created during the build process might not be needed. In this case it is safe to remove the associated rules from the makefile (for example the rule to build libembedded-chicken.a in the case the application is not embedded into a C module). Most of the time not all library units are needed for a given application. For the example above, a minimal makefile would look like this:
        CC = gcc
        CFLAGS = -I. -O3 -fomit-frame-pointer -fstrict-aliasing
        
        foo : foo.o bar.o libchicken0.a libstuffed-chicken0.a
                gcc -s -L. foo.o bar.o -o $@ -lchicken0 -lstuffed-chicken0
        foo.o : foo.c chicken.h
        bar.o : bar.c chicken.h
        
        libchicken0.a : runtime.o library.o eval.o
        	ar rus $@ $^
        libstuffed-chicken0.a : regex.o unistd.o
        	ar rus $@ $^
        runtime.o : runtime.c chicken.h
        eval.o : eval.c chicken.h
        library.o : library.c chicken.h
        regex.o : regex.c chicken.h
        unistd.o : unistd.c chicken.h
        
      • Most library units can be used independently. Here is a table that shows library units that depend on other library units:
        formatextras
        srfi-13srfi-14
        unistdregex
        lolevelsrfi-4 extras
        tinyclosextras

        In the example above bar uses unistd, which in turn uses regex. The units library and eval are used by foo (these are used by default).
        The file runtime is needed in any case.

  5. Using the interpreter
  6. CHICKEN provides a simple interpreter for evaluating Scheme programs and expressions. This interpreter can be used on its own and a simple read-eval-print loop is provided in the file csi.scm.

    1. Command line format
      csi {FILENAME|OPTION}
      where FILENAME specifies a file with Scheme source-code. If the extension of the source-file is .scm, it may be omitted. The runtime options described in Runtime options are also available for the interpreter. If the environment variable CSI_OPTIONS is set to a list of options, then these options are additionally passed to every direct or indirect invocation of csi. Please note that runtime options (like -:...) can not be passed using this method. The options recognized by the interpreter are:
      --
      Ignore everything on the command-line following this marker. Runtime options ("-:...") are still recognized.
      -case-sensitive
      Enables the reader to read symbols case sensitive. The default is to read non case sensitive. This option registers the case-sensitive feature identifier.
      -batch
      Quit the interpreter after processing all command line options.
      -eval EXPRESSIONS
      Evaluate EXPRESSIONS.
      -feature SYMBOL
      Registers SYMBOL to be a valid feature identifier for cond-expand.
      -help
      Write a summary of the available command line options to standard ouput and exit.
      -hygienic
      Load syntax-case macro package and enable high-level macros in interpreted code. This option registers the hygienic-macros feature identifier.
      -include-path PATHNAME
      Specifies an alternative search-path for files included via the include special form. This option may be given multiple times. If the environment variable CHICKEN_INCLUDE_PATH is set, it should contain a list of alternative include pathnames separated by ";". The environment variable CHICKEN_HOME is also considered as a search path.
      -no-feature SYMBOL
      Unregisters feature identifier SYMBOL.
      -no-init
      Do not load initialization-file. If this option is not given and the file ~/.csirc exists, then it is loaded before the read-eval-print loop commences.
      -no-warnings
      Disables any warnings that might be issued by the reader or evaluated code.
      -quiet
      Do not print a startup message.
      -script
      This is equivalent to -batch -quiet, but also ignores all arguments after the argument following -script.
      -srfi-7
      Process any source files as SRFI-7 configuration language. (see: the SRFI-7 document).
      -strict
      Disable non-standard macros.
      -strict-srfi-0
      Disable non-standard macros except cond-expand.
      -version
      Write the banner with version information to standard output and exit.

    2. Writing Scheme scripts
      • Since UNIX shells use the #! notation for starting scripts, the interpreter registers the special read-syntax #! as a comment and the reader ignores everything after the two characters up to the end of the current line.

        The easiest way is to use the -script option like this:

          % cat foo
          #! /usr/local/bin/csi -script
          (print (eval (with-input-from-string (car (command-line-arguments)) read)))
        
          % chmod +x foo
          % foo "(+ 3 4)"
          7
        

        The parameter command-line-arguments is set to a list of the parameters that were passed to the Scheme script.
        Scripts can be compiled to standalone executables.

      • CHICKEN implements SRFI-22 and provides the Scheme script interpreters scheme-r4rs, scheme-ieee-1178-1990, scheme-r5rs, scheme-srfi-0 and scheme-srfi-7.
        Scheme scripts can be compiled, the compiler determines language dialect from the invocation line:

          % cat bar
          #! /usr/bin/env scheme-r5rs
          (define (main args)
            (write (list->string (reverse (string->list (cadr args)))))
            (newline) )
        
          % chmod +x bar
          % bar "one two three"
          "eerht owt eno"
          % chicken bar -output-file bar.c -quiet
          % gcc bar.c `chicken-config -cflags -libs` -o cbar
          % cbar "one two three"
          "eerht owt eno"
        

        For more information, see the SRFI-22 document.

        Note: The Scheme script interpreters scheme-r5rs and scheme-srfi-0 invoke the CHICKEN interpreter (csi) with the -hygienic option, which loads the highlevel macro definitions from a file. This will result in slightly longer startup times for these scripts than for, say, scripts invoked via scheme-r4rs.
        Compiling the script to native code will of course eliminate the problem.

    3. Toplevel commands

      The toplevel loop understands a number of special commands:

      ,?
      Show summary of available toplevel commands.
      ,NUM
      Evaluate NUMth command in history-list
      ,h
      List history of last commands
      ,l FILENAME
      Load file with given FILENAME (may be a symbol or string).
      ,ln FILENAME
      Load file and print result(s) of each top-level expression.
      ,p EXP
      Pretty-print evaluated expression EXP.
      ,d EXP
      Describe result of evaluated expression EXP.
      ,q
      Quit the interpreter.
      ,s STRING-OR-SYMBOL
      Execute shell-command.
      ,t EXP
      Evaluate form and print elapsed time.
      ,ts
      Show a list of all threads that are ready for scheduling.
      ,x EXP
      Pretty-print macroexpanded expression EXP (the expression is not evaluated).
      ,x1 EXP
      Pretty-print expression EXP. If the expression is a macro form, then it is expanded once (the expression is not evaluated).

    4. Macros and procedures implemented in the interpreter

      The interpreter contains the definitions of the library units extras, srfi-1 and syntax-case, the describe facility and report (see Additional files). If available, the units unistd and regex are also included.
      Additional macros and procedures available in the interpreter are:

      [syntax] (autoload FILENAME (SYMBOL ...))
      The first invocation of any one of the global procedures named SYMBOL ... will load the Scheme source file FILENAME and replace each of the procedures with its actual definition. Say the file foo.scm has the following contents:
      ;;; foo.scm
      
      (define (bar x) (* x 2))
      
      Then
      (autoload "foo.scm" (bar))
      (bar 2)
      ; loading foo.scm ...
                                 ==> 4
      
      [syntax] (trace SYMBOL ...)
      Switches tracing on for the procedures with the given names.
      [syntax] (untrace SYMBOL ...)
      Switches tracing off.
      [procedure] ($ [INDEX])
      Returns entry number INDEX in the history list.
      [procedure] (& [INDEX])
      Returns result of entry number INDEX in the history list.

    5. Extending the interpreter

      The interpreter csi can be recompiled and relinked with arbitrary compiled Scheme modules. A Scheme script named extend-csi is provided on UNIX-compatible systems which makes this process quite easy. Consider we have this file, named foo.scm:

      (declare (unit foo))
      
      (define (foo) (print "Hello!"))
      

      To compile the library unit foo and add it to the interpreter we can perform the following steps:

        % chicken foo.scm -explicit-use -output-file foo.c -quiet
        % gcc -c foo.c `chicken-config -cflags` -o foo.o
        % extend-csi foo -output-file csifoo
        chicken /usr/local/share/chicken/src/csi.scm -optimize-level 1 -quiet -postlude "(##csi#run)" \
         -prologue /usr/local/share/chicken/src/build.scm -prelude '(declare (uses regex unistd))' \
         -prelude "(declare (uses foo))"
        gcc out.c foo.o `chicken-config -cflags -libs -extra-libs` -o csifoo
        rm -f out.c foo.o
        % csifoo -quiet
        >>> (foo)
        foo!
        >>>
      

      For more information enter extend-csi without arguments at the command line.


  7. Supported language
    1. Deviations from the standard

      [4.1.3] A compiled procedure may not have more than 126 arguments. On x86 platforms this limit is raised to 1024.

      [6.2.4] The runtime system uses the numerical string-conversion routines of the underlying C library and so does only understand standard (C-library) syntax for floating-point constants.

      [6.2.5] The routines complex?, real? and rational? are identical to the standard procedure number?. The procedures numerator, denominator and rationalize are not implemented. Also not implemented are all procedures related to complex numbers.

      [6.2.6] The procedure string->number can not parse complex numbers and does not obey write/read invariance on inexact numbers.

      [6.4] The maximum number of values that can be passed to continuations captured using call-with-current-continuation is 126.

      [6.5] eval ignores its second argument. Code evaluated in scheme-report-environment or null-environment still sees non-standard syntax.

      [6.6.2] The procedure char-ready? is handling terminal input ports only under DJGPP correctly. On other platforms it returns always #t.
      The procedure read can not parse complex numbers and does not obey write/read invariance on inexact numbers.

      [6.6.3] The procedures write and display do not obey write/read invariance to inexact numbers.

    2. Extensions to the standard

      [2.1] Identifiers may contain special characters if delimited with | ... |.

      [2.3] The brackets [ ... ] are provided as an alternative syntax for ( ... ).
      A number of reader extensions is provided. See Non-standard read syntax.

      [4] Numerous non-standard macros are provided. See Non-standard macros and special forms for more information.

      [4.2.3] (begin) is allowed in non-toplevel contexts and evaluates to an unspecified value.

      [4.2.5] Delayed expressions may return multiple values.

      [5.2.1] A define occurring anywhere but at the beginning of a lambda- or let-body is in every aspect equivalent to set!.

      [5.2.2] define-values may be used in internal definitions if the R5RS macro system is not used.

      [6] CHICKEN provides numerous non-standard procedures. See the manual sections on library units for more information.

      [6.3.4] User defined character names are supported. See char-name.

      [6.3.5] CHICKEN supports special characters preceded with a backslash (\) in quoted string constants. \n denotes the newline-character and \t is equivalent to the TAB character.

      [6.4] force called with an argument that is not a promise returns that object unchanged.
      Captured continuations can be safely invoked inside before- and after-thunks of a dynamic-wind form and execute in a dynamic context in which the particular thunks are not established.

      [6.6.1] The procedures open-input-file, open-output-file, with-input-from-file, with-output-to-file, call-with-input-file and call-with-output-file accept an optional second (or third) argument which should be a keyword, if supplied. This argument specifies the mode in which the file is opened. Possible values are the keywords #:text, #:binary or #:append.

    3. Non standard read syntax
      [read syntax] #| ... |#
      A multiline "block" comment. May be nested.
      [read syntax] #;EXPRESSION
      Treats EXPRESSION as a comment.
      [read syntax] #,(CONSTRUCTORNAME DATUM ...)
      Allows user-defined extension of external representations. (For more information see documentation for SRFI-10).
      [read syntax] #'EXPRESSION
      An abbreviation for (syntax EXPRESSION).
      [read syntax] #:SYMBOL
      Syntax for keywords. Keywords are symbols that evaluate to themselves, and as such don't have to be quoted.
      [read syntax] #<<TAG
      Specifies a multiline string constant. Anything up to a line equal to TAG will be returned as a single string:
      (define msg #<<END
      "Hello, world!", he said.
      END
      )
      
      is equivalent to
      (define msg "\"Hello, world!\", he said.")
      
      [read syntax] #<#TAG
      Similar to #<<, but allows substitution of embedded Scheme expressions prefixed with # and optionally enclosed in { ... }. Two consecutive #s are translated to a single #:
      (define three 3)
      (display #<#EOF
      This is a simple string with an embedded `##' character
      and substituted expressions: (+ three 99) ==> #(+ three 99)
      (three is "#{three}")
      EOF
      )
      
      prints
      This is a simple string with an embedded `#' character
      and substituted expressions: (+ three 99) ==> 102
      (three is "3")
      

    4. Non-standard macros and special forms

      1. Binding forms for optional arguments:
        [syntax] (:optional ARGS DEFAULT)
        Use this form for procedures that take a single optional argument. If ARGS is the empty list DEFAULT is evaluated and returned, otherwise the first element of the list ARGS. It is an error if ARGS contains more than one value.
        (define (incr x . i) (+ x (:optional i 1)))
        (incr 10)                                   ==> 11
        (incr 12 5)                                 ==> 17
        
        [syntax] (case-lambda (LAMBDA-LIST1 EXP1 ...) ...)
        SRFI-16. Expands into a lambda that invokes the body following the first matching lambda-list.
        (define plus
          (case-lambda 
            (() 0)
            ((x) x)
            ((x y) (+ x y))
            ((x y z) (+ (+ x y) z))
            (args (apply + args))))
        
        (plus)                      ==> 9
        (plus 1)                    ==> 1
        (plus 1 2 3)                ==> 6
        
        For more information see documentation for SRFI-16.
        [syntax] (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)
        [syntax] (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)
        Binding constructs for optional procedure arguments. ARGS should be a rest-parameter taken from a lambda-list. let-optionals binds VAR1 ... to available arguments in parallel, or to DEFAULT1 ... if not enough arguments were provided. let-optionals* binds VAR1 ... sequentially, so every variable sees the previous ones. If a single variable RESTVAR is given, then it is bound to any remaining arguments, othersise it is an error if any excess arguments are provided.
        (let-optionals '(one two) ((a 1) (b 2) (c 3))
          (list a b c) )                              ==> (one two 3)
        (let-optionals* '(one two) ((a 1) (b 2) (c a))
          (list a b c) )                               ==> (one two one)
        
        [syntax] (let-string-start+end (START END [REST]) PROCEXP SEXP ARGEXP BODY ...)
        Extracts optional string start/end values from argument list. See documentation for SRFI-13.

      2. Other binding forms:
        [syntax] (and-let* (BINDING ...) EXP1 EXP2 ...)
        SRFI-2. Bind sequentially and execute body. BINDING can be a list of a variable and an expression, a list with a single expression, or a single variable. If the value of an expression bound to a variable is #f, the and-let* form evaluates to #f (and the subsequent bindings and the body are not executed). Otherwise the next binding is performed. If all bindings/expressions evaluate to a true result, the body is executed normally and the result of the last expression is the result of the and-let* form. See also documentation for SRFI-2.
        [syntax] (define-values (NAME ...) EXP)
        Defines several variables at once, with the result values of expression EXP. This form may also be used in internal definitions.
        [syntax] (fluid-let ((VAR1 X1) ...) BODY ...)
        Binds the variables VAR1 ... dynamically to the values X1 ... during execution of BODY ....
        [syntax] (let-values (((NAME ...) EXP) ...) BODY ...)
        Binds multiple variables to the result values of EXP .... All variables are bound simultaneously.
        [syntax] (let*-values (((NAME ...) EXP) ...) BODY ...)
        Binds multiple variables to the result values of EXP .... The variables are bound sequentially.
        (let*-values (((a b) (values 2 3))
                      ((p) (+ a b)) )
          p)                               ==> 5
        
        [syntax] (letrec-values (((NAME ...) EXP) ...) BODY ...)
        Binds the result values of EXP ... to multiple variables at once. All variables are mutually recursive.
        (letrec-values (((odd even)
                           (values 
                             (lambda (n) (if (zero? n) #f (even (sub1 n))))
                             (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
          (odd 17) )                                                              ==> #t
        
        [syntax] (parameterize ((PARAMETER1 X1) ...) BODY ...)
        Binds the parameters PARAMETER1 ... dynamically to the values X1 ... during execution of BODY .... (see also: make-parameter)
        [syntax] (receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
        SRFI-8. Syntactic sugar for call-with-values. Binds variables to the result values of VALUEEXP and evaluates BODY ....
        [syntax] (set!-values (NAME ...) EXP)
        Assigns the result values of expression EXP to multiple variables.

      3. Substitution forms and macros:
        [syntax] (define-constant (NAME VAR ... [. VAR]) BODY ...)
        [syntax] (define-constant NAME CONST)
        Define a variable with a constant value. Any reference to such a constant should appear textually after it's definition. This construct is equivalent to define when evaluated or interpreted. Constant definitions should only appear at toplevel. Note that constants are local to the current compilation unit and are not available outside of the source-file in which they are defined. Names of constants still exist in the Scheme namespace and can be lexically shadowed.
        If the value is mutable, then the compiler is careful to preserve its identity.
        [syntax] (define-id-macro NAME EXP)
        Defines a globally visible identifier macro. Every occurrence of the variable NAME will be substituted by the expression EXP. Note that EXP is not evaluated at macro-definition time.
        Only global identifier macros can be defined using this form.
        [syntax] (define-inline (NAME VAR ... [. VAR]) BODY ...)
        [syntax] (define-inline NAME EXP)
        [syntax] (define-integrable (NAME VAR ... [. VAR]) BODY ...)
        [syntax] (define-integrable NAME EXP)
        Defines an inline procedure. Any occurrence of NAME will be replaced by EXP or (lambda (VAR ... [. VAR]) BODY ...). This is similar to a macro, but variable-names and -scope will be correctly handled. Inline substitutions take place after macro-expansion. EXP should be a lambda-expression. Any reference to NAME should appear textually after it's definition. Note that inline procedures are local to the current compilation unit and are not available outside of the source-file in which they are defined. Names of inline procedures still exist in the Scheme namespace and can be lexically shadowed. This construct is equivalent to define when evaluated or interpreted. Inline definitions should only appear at toplevel. define-integrable is just a synonym for define-inline.
        [syntax] (define-macro (NAME VAR ... [. VAR]) EXP1 ...)
        [syntax] (define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
        Define a globally visible macro special form. The macro is available as soon as it is defined, i.e. it is registered at compile-time. If the file containing this definition invokes eval, then the macro is visible in evaluated expressions during runtime. The second possible syntax for define-macro is allowed for portability purposes only. In this case the second argument must be a lambda-expression.
        Only global macros can be defined using this form.
        [syntax] (let-id-macro ((NAME EXP) ...) EXP1 ...)
        Defines an identifier macro. Every occurrence of the variable NAME will be substituted by the expression EXP. The defined identifier macros are only valid inside the body EXP1 .... Note that the EXP forms are not evaluated at macro-definition time.
        [syntax] (let-macro (MACRODEF ...) EXP1 ...)
        Defines locally scoped macros. MACRODEF may be of the form (NAME (lambda LAMBDALIST BODY ...)) or of the form ((NAME . LAMBDALIST) BODY ...). The defined macros are only valid inside the body EXP1 ....

      4. Conditional forms:
        [syntax] (unless TEST EXP1 EXP2 ...)
        Equivalent to:
        (if (not TEST) (begin EXP1 EXP2 ...))
        
        [syntax] (when TEST EXP1 EXP2 ...)
        Equivalent to:
        (if TEST (begin EXP1 EXP2 ...))
        

      5. Record structures:
        [syntax] (define-record NAME SLOTNAME ...)
        Defines a named structure. Call make-NAME to create an instance of the structure (with one initialization-argument for each slot). (NAME? STRUCT) tests any object for being an instance of this structure. Slots are accessed via (NAME-SLOTNAME STRUCT) and updated using (NAME-SLOTNAME-set! STRUCT VALUE).
        (define-record point x y)
        (define p1 (make-point 123 456))
        (point? p1)                      ==> #t
        (point-x p1)                     ==> 123
        (point-y-set! p1 99)
        (point-y p1)                     ==> 99
        
        [syntax] (define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)
        [syntax] (define-record-printer NAME PROCEDURE)
        Defines a printing method for record of the type NAME by associating a procedure with the record type. When a record of this type is written using display, write or print, then the procedure is called with two arguments: the record to be printed and an output-port.
        (define-record foo x y z)
        (define f (make-foo 1 2 3))
        (define-record-printer (foo x out)
          (fprintf out "#,(foo ~S ~S ~S)" (foo-x x) (foo-y x) (foo-z x)) )
        (define-reader-ctor 'foo make-foo)
        (define s (with-output-to-string (lambda () (write f))))
        s                                                                  ==> "#,(foo 1 2 3)"
        (equal? f (with-input-from-string s read)))                        ==> #t
        
        [syntax] (record-case EXP ((HEAD1 VAR1 ...) BODY1 ...) ... [(else BODYN ...)])
        Executes the first clause BODY ... that matches the record EXP, which should be a record of a type defined by define-record. A clause matches if the symbol HEAD is equal to the record type of EXP and the record has at least the same number of slots as variables VAR ... are specified. If a clause matches, the variables VAR ... are bound to the corresponding slot-values of the matched record. If no clause matches the given structure, an unspecified value is returned.
        (define-record foo x y)
        (define f1 (make-foo 123 456))
        (record-case f1
          ((bar p q r) (list "bar" p q r))
          ((foo a b) (list "foo" a b))
          (else "none") )                  ==> ("foo" 123 456)
        
        Note that this form has nothing to do with the record-case macro used in Chez Scheme.

      6. Other forms:
        [syntax] (assert EXP [STRING ARG ...])
        Signal error if EXP evaluates to false. An optional message STRING and arguments ARG ... may be supplied to give a more informative error-message.
        [syntax] (cond-expand FEATURE-CLAUSE ...)
        SRFI-0. Expands by selecting feature clauses. Predefined feature-identifiers are srfi-0, srfi-2, srfi-6, srfi-8, srfi-10 and chicken. If the source-file containing this form is currently compiled, the feature compiling is defined. For further information, see documentation for SRFI-0 This form is allowed to appear in non-toplevel expressions.
        [syntax] (critical-section BODY ...)
        Evaluate BODY ... with interrupts temporarily disabled.
        [syntax] (eval-when (SITUATION ...) EXP ...)
        Controls evaluation/compilation of subforms. SITUATION should be one of the symbols eval, compile or load. When encountered in the evaluator, and the situation specifier eval is not given, then this form is not evaluated and an unspecified value is returned. When encountered in compiled code, and the situation specifier compile is given, then this form is evaluated during the compilation process. When encountered in compiled code, and the situation specifier load is not given, then this form is ignored and an expression resulting into an unspecified value is compiled instead.

        Note: it is currently not possible to use define-syntax or define inside eval-when forms when hygienic macros are enabled.

        [syntax] (include STRING)
        Include toplevel-expressions from a given source-file in the currently compiled/interpreted program. If the included file has the extension .scm, then it may be omitted. The file is searched in the current directory and, if not found, in all directories specified in the -include-path option. The expressions are treated as toplevel expressions, so it's generally a good idea to use include only in a toplevel context.
        [syntax] (nth-value N EXP)
        Returns the Nth value (counting from zero) of the values returned by expression EXP.
        [syntax] (time EXP)
        Evaluate EXP and print elapsed time and memory information.

    5. Declarations
      [syntax] (declare DECLSPEC ...)
      Process declaration specifiers. Declarations always override any command-line settings. Declarations are valid for the whole compilation-unit (source file), the position of the declaration in the source file can be arbitrary. DECLSPEC may be any of the following:
      [declaration specifier] (always-bound SYMBOL ...)
      Declares that the given variables are always bound and accesses to those have not to be checked.
      [declaration specifier] (block)
      Assume global variables are never redefined. This is the same as specifying the -block option.
      [declaration specifier] (bound-to-procedure SYMBOL ...)
      Declares that the given identifiers are always bound to procedure values.
      [declaration specifier] (foreign-declare STRING ...)
      Include given strings verbatim into header of generated file.
      [declaration specifier] (inline)
      Enable inlining. This is the same as specifying the -inline option.
      [declaration specifier] (inline-limit NUMBER)
      Specify maximal program growth. This is the same as specifying the -inline-limit option (see: Using the compiler).
      [declaration specifier] (interrupts-enabled)
      Enable timer-interrupts checks in the compiled program (the default).
      [declaration specifier] (disable-interrupts)
      [declaration specifier] (interrupts-disabled)
      [declaration specifier] (not interrupts-enabled)
      Disable timer-interrupts checks in the compiled program. Threads can not be preempted in main- or library-units that contain this declaration.
      [declaration specifier] (no-fancy-ports)
      Declares that standard I/O operations work on basic file- and console ports, only. Certain I/O operations can then be replaced by C stream I/O function calls.
      [declaration specifier] (no-winding-callcc)
      Declares that all known uses of call-with-current-continuation use non-winding semantics. So any invocation of captured continuations will not execute any pending before- or after-thunks. This means that the following forms should be used with care, since they expand into or call dynamic-wind:
      critical-section
      dynamic-wind
      fluid-let
      with-exception-handler
      handle-exceptions
      
      [declaration specifier] (notinline)
      [declaration specifier] (not inline)
      Disable inlining (the default).
      [declaration specifier] ([number-type] TYPE)
      [declaration specifier] (fixnum-arithmetic)
      Declares that only numbers of the given type are used. TYPE may be fixnum, flonum or generic (which is the default).
      [declaration specifier] ([not] standard-bindings SYMBOL ...)
      Declares that all given standard procedures (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given standard bindings are assumed to be never redefined.
      [declaration specifier] ([not] extended-bindings SYMBOL ...)
      Declares that all given non-standard and CHICKEN-specific procedures (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given extended bindings are assumed to be never redefined.
      [declaration specifier] ([not] usual-integrations SYMBOL ...)
      Declares that all given standard and extended bindings (or all if no symbols are specified) are never globally redefined. If not is specified, then all but the given standard and extended bindings are assumed to be never redefined.
      [declaration specifier] (unit SYMBOL)
      Specify compilation unit-name (if this is a library)
      [declaration specifier] (unsafe)
      [declaration specifier] (not safe)
      Do not generate safety-checks. This is the same as specifying the -unsafe option.
      [declaration specifier] (uses SYMBOL ...)
      Gives a list of used library-units. Before the toplevel-expressions of the main-module are executed, all used units evaluate their toplevel-expressions in the order in which they appear in this declaration. If a library unit A uses another unit B, then B's toplevel expressions are evaluated before A's. Furthermore, the used symbols are registered as features during compile-time, so cond-expand knows about them.

    6. Interface to external functions and variables

      1. Accessing external objects:
        [syntax] (define-foreign-parameter NAME TYPE [STRING])
        Similar to define-foreign-variable, but defines a globally (and externally) visible procedure that accesses the foreign variable named STRING (or NAME if STRING is not supplied) like a parameter: calling the procedure with no arguments returns the current value of the variable, calling it with an argument updates the variable's value. Note that you shouldn't use this form to access C macros, since any assignment may be incorrect (STRING has to specify an lvalue).
        (define-foreign-parameter errno int)
        (errno 0)
        (errno)                              ==> 0
        (errno 123)
        (errno)                              ==> 123
        
        [syntax] (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
        Defines an alias for TYPE. TYPE may be a type-specifier or a string, naming a C type. The namespace of foreign type specifiers is separate from the normal Scheme namespace.
        The optional arguments ARGCONVERT and RETCONVERT should evaluate to procedures that map argument- and result-values to a value that can be transformed to TYPE:
        (declare
          (uses srfi-4)
          (foreign-declare "int foo(char *ptr, int i) { return(ptr[ i ]); }") )
        (define-foreign-type bvector pointer u8vector->byte-vector)
        ((foreign-lambda int "foo" bvector int) '#u8(100 101 102) 1)            ==> 101
        
        [syntax] (define-foreign-variable NAME TYPE [STRING])
        Defines a foreign variable of name NAME. STRING should be the real name of a foreign variable or parameterless macro. If STRING is not given, then the variable name NAME will be converted to a string and used instead. All references and assignments (via set!) are modified to correctly convert values between Scheme and C representation. This foreign variable can only be accessed in the current compilation unit, but the name can be lexically shadowed.
        Note that STRING can name an arbitrary C expression. If no assignments are performed, then STRING doesn't even have to specifiy an lvalue.
        [syntax] (foreign-callback-lambda RETURNTYPE NAME ARGTYPE)
        This is similar to foreign-lambda, but also allows the called function to call Scheme functions. See Callbacks.
        [syntax] (foreign-callback-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
        This is similar to foreign-lambda*, but also allows the called function to call Scheme functions. See Callbacks.
        [syntax] (foreign-lambda RETURNTYPE NAME ARGTYPE ...)
        Represents a binding to an external routine. This form can be used in the position of an ordinary lambda expression. NAME specifies the name of the external procedure and should be a string or a symbol.
        [syntax] (foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
        Similar to foreign-lambda, but instead of generating code to call an external function, the body of the C procedure is directly given in STRING ...:
        (define my-strlen
          (foreign-lambda* int ((c-string str))
            "int n = 0;
             while(*(str++)) ++n;
             return(n);") )
        
        (my-strlen "one two three")             ==> 13
        
        For obscure technical reasons any use of the return statement should enclose the result value in parantheses. For the same reasons return without an argument is not allowed.

      2. Foreign type specifiers:

        Here is a list of valid foreign type specifiers:

        scheme-object
        An arbitrary Scheme data object (immediate or non-immediate).
        bool
        As argument: any value (#f is false, anything else is true).
        As result: anything different from 0 and the NULL-pointer is #t.
        char
        unsigned-char
        A character.
        short
        unsigned-short
        A short integer number.
        int
        unsigned-int
        An small integer number in fixnum range (at least 30 bit).
        integer
        unsigned-integer
        Either a fixnum or a flonum in the range of a (unsigned) machine "int".
        long
        unsigned-long
        Either a fixnum or a flonum in the range of a (unsigned) machine "long".
        float
        double
        A floating-point number. If an exact integer is passed as an argument, then it is automatically converted to a float.
        pointer
        An untyped pointer to the contents of a non-immediate Scheme object (not allowed as return type). The value #f is also allowed and is passed as a NULL pointer.
        c-pointer
        An untyped operating-system pointer. The value #f is also allowed and is passed as a NULL pointer.
        c-string
        A C string (terminated by a '\0' character). The value #f is also allowed and is passed as a NULL pointer. If uses as the type of a return value, a NULL pointer will be returned as #f.
        void
        Specifies an undefined return value. Not allowed as argument type.
        (pointer TYPE)
        An operating-system pointer to an object of TYPE.
        (struct NAME)
        A struct of the name NAME, which should be a string. Structs can not be directly passed as arguments to foreign function, neither can they be result values. Pointers to structs are allowed, though.
        (union NAME)
        A union of the name NAME, which should be a string. Unions can not be directly passed as arguments to foreign function, neither can they be result values. Pointers to unions are allowed, though.
        (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
        A function pointer. CALLCONV specifies an optional calling convention and should be a string. The meaning of this string is entirely platform dependent. The value #f is also allowed and is passed as a NULL pointer.

      3. Entry points:

        To simplify embedding compiled Scheme code into arbitrary programs, one can define so called "entry points", which provide a uniform interface and parameter conversion facilities.

        [syntax] (define-entry-point INDEX ((VAR1 TYPE1) ...) (RTYPE1 ...) EXP1 EXP2 ...)
        Defines a new entry-point with index INDEX which should evaluate to an exact integer. During execution of the body EXP1 EXP2 ... the variables VAR1 ... are bound to the parameters passed from the host program to the invoked entry point. The parameters passed are converted according to the foreign type specifiers TYPE1 .... The expressions should return as many values as foreign type specifiers are given in RTYPE1 .... The results are then transformed into values that can be used in the host program.

        Note: if one or more of the result types RTYPE ... specify the type c-string, then the parameter type at the same positions in TYPE1 ... have to be c-strings as well, because the result strings are copied into the same area in memory. You should also take care that the passed parameter buffer is long enough to hold the result string or unpredictable things will happen.

        If entry points were defined then the program will not terminate after execution of the last toplevel expression, but instead it will enter a loop that waits for the host to invoke one of the defined entry points.

        The following C functions and data types are provided:

        void CHICKEN_parse_command_line(int argc, char *argv[], int *heap, int *stack int *symbols)
        Parse the programs command-line contained in argc and argv and return the heap-, stack- and symbol-table limits given by runtime options of the form -:..., or choose default limits. The library procedure argv can access the command-line only if this function has been called by the containing application.
        int CHICKEN_initialize(int heap, int stack, int symbols)
        Initializes the Scheme execution context and memory. heap holds the number of bytes that are to be allocated for the secondary heap. stack holds the number of bytes for the primary heap. symbols contains the size of the symbol table. Passing 0 to one ore more of these parameters will select a default size. Calling this function more than once has no effect. If enough memory is available and initialization was successful, then 1 is returned, otherwise this function returns 0.
        void CHICKEN_run(void **data, int *bytes, int *maxlen)
        Starts the Scheme program. data, bytes and maxlen contain invocation parameters in raw form. Pass NULL here. Call this function once to execute all toplevel expressions in your compiled Scheme program. If the runtime system was not initialized before, then CHICKEN_initialize is called with default sizes.
        void CHICKEN_invoke(int index, C_parameter *params, int count)
        Invoke the entry point with index index. count should contain the number of parameters passed. params is a pointer to parameter data:
        typedef union
        {
          long i;             /* parameter type bool, [unsigned] int/short/long */
          long c;             /* parameter type [unsigned] char */
          double f;           /* parameter type float/double */
          void *p;            /* any pointer parameter type and C strings */
        } C_parameter;

        This function calls CHICKEN_run if it was not called at least once before.

        Here is a simple example (assuming a UNIX-like environment):

        % cat foo.c
        #include <stdio.h>
        #include "chicken.h"
        
        int main(void)
        {
          C_parameter p[ 3 ];
          char str[ 32 ] = "hello!";    /* We need some space for the result string! */
        
          memset(p, 0, sizeof(p));
          p[ 0 ].i = -99;
          p[ 1 ].p = str;
          p[ 2 ].f = 3.14;
          CHICKEN_invoke(1, p, 3);
          printf("->\n%d\n%s\n", p[ 0 ].i, p[ 1 ].p);
          return 0;
        }
        
        % cat bar.scm
        (define-entry-point 1
            ((a integer) (b c-string) (c double))
            (int c-string)
          (print (list a b c))
          (values 123 "good bye!") )
        
        % chicken bar.scm -output-file bar.c -quiet
        % gcc foo.c bar.c -o foo `chicken-config -cflags -emb-libs`
        % foo
        (-99 "hello!" 3.14)
        ->
        123
        good bye!
        

        Note the use of -emb-libs. We have to link with a different runtime library, because the host program provides a main function.

      4. Callbacks:

        To enable an external C function to call back to Scheme, the form foreign-callback-lambda (or foreign-callback-lambda*) has to be used. This generates special code to save and restore important state information during execution of C code. There are two ways of calling Scheme procedures from C: the first is to invoke the runtime function C_callback with the closure to be called and the number of arguments. The second is to define an externally visible wrapper function around a Scheme procedure with the define-external or foreign-callback-wrapper forms.

        [syntax] (define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)
        [syntax] (define-external NAME TYPE [INIT])
        The first form defines an externally callable Scheme procedure. NAME should be a symbol, which, when converted to a string, represents a legal C identifier. ARGUMENTTYPE1 ... and RETURNTYPE are foreign type specifiers for the argument variables VAR1 ... and the result, respectively.
        QUALIFIERS is an optional qualifer for the foreign procedure definition, like __stdcall.
        (define-external (foo (c-string x)) int (string-length x))
        
        is equivalent to
        (define foo (foreign-callback-wrapper int "foo" "" (c-string) (lambda (x) (string-length x))))
        

        The second form of define-external can be used to define variables that are accessible from foreign code. It declares a global variable named by the symbol NAME and that has the type TYPE. INIT can be an arbitrary expression that is used to initialize the variable. NAME is accessible from Scheme just like any other foreign variable defined by define-foreign-variable.
        Note: don't be tempted to assign strings or bytevectors to external variables. Garbage collection moves those objects around, so it is very bad idea to assign pointers to heap-data. If you have to do so, then copy the data object into statically allocated memory (for example by using evict).

        [syntax] (external-pointer NAME)
        NAME should be an external variable defined by (define-external NAME ...). This form returns a pointer object that contains the address of the variable NAME.
        (define-external foo int)
        ((foreign-lambda* void (((pointer int) ip)) "*ip = 123;") (external-pointer foo))
        foo                                                                               ==> 123
        
        [syntax] (foreign-callback-wrapper RETURNTYPE NAME QUALIFIERS (ARGUMENTTYPE1 ...) EXP)
        Defines an externally callable wrapper around the procedure EXP. EXP must be a lambda expression of the form (lambda ...). The wrapper will have the name NAME and will have a signature as specified in the return- and argument-types given in RETURNTYPE and ARGUMENTTYPE1 .... QUALIFIERS is a qualifier string for the function definition (see define-external).
        C_word C_callback(C_word closure, int argc)
        This function can be used to invoke the Scheme procedure closure. argc should contain the number of arguments that are passed to the procedure on the temporary stack. Values are put onto the temporary stack with the C_save macro.
        void C_save(C_word x)
        Saves the Scheme data object x on the temporary stack.
        C_word C_fix(int integer)
        C_word C_make_character(int char_code)
        C_word C_SCHEME_END_OF_LIST
        C_word C_SCHEME_END_OF_FILE
        C_word C_SCHEME_FALSE
        C_word C_SCHEME_TRUE
        These macros return immediate Scheme data objects.
        C_word C_string(C_word **ptr, int length, char *string)
        C_word C_string2(C_word **ptr, char *zero_terminated_string)
        C_word C_intern2(C_word **ptr, char *zero_terminated_string)
        C_word C_pair(C_word **ptr, C_word car, C_word cdr)
        C_word C_flonum(C_word **ptr, double number)	
        C_word C_int_to_num(C_word **ptr, int integer)
        C_word C_mpointer(C_word **ptr, void *pointer)
        C_word C_vector(C_word **ptr, int length, ...)
        C_word C_list(C_word **ptr, int length, ...)
        These functions allocate memory from ptr and initialize a fresh data object. The new data object is returned. ptr should be the address of an allocation pointer created with C_alloc.
        C_word *C_alloc(int words)
        Allocates memory from the C stack and returns a pointer to it. words should be the number of words needed for all data objects that are to be created in this function. Note that the allocated data objects have to be passed to the Scheme function, or they will not be seen by the garbage collector. Note also that the allocated memory will not be available after invocation of the Scheme procedure, so only small or medium sized objects should be created that way.
        int C_SIZEOF_LIST(int length)
        int C_SIZEOF_STRING(int length)
        int C_SIZEOF_VECTOR(int length)
        int C_SIZEOF_INTERNED_SYMBOL(int length)
        int C_SIZEOF_PAIR
        int C_SIZEOF_FLONUM
        int C_SIZEOF_POINTER
        These are macros that return the size in words needed for a data object of a given type.
        int C_character_code(C_word character)
        int C_unfix(C_word fixnum)
        double C_flonum_magnitude(C_word flonum)
        char *C_c_string(C_word string)
        int C_num_to_int(C_word fixnum_or_flonum)
        void *C_pointer_address(C_word pointer)
        These macros and functions can be used to convert Scheme data objects back to C data.
        int C_header_size(C_word x)
        int C_header_bits(C_word x)
        Return the number of elements and the type-bits of the non-immediate Scheme data object x.
        C_word C_block_item(C_word x, int index)
        This macro can be used to access slots of the non-immediate Scheme data object x. index specifies the index of the slot to be fetched, starting at 0. Pairs have 2 slots, one for the car and one for the cdr. Vectors have one slot for each element.
        C_word C_make_header(C_word bits, C_word size)
        A macro to build a Scheme object header from its bits and size parts.
        C_word C_symbol_value(C_word symbol)
        Returns the global value of the variable with the name symbol.

        An example:

        % cat foo.scm
        (declare (foreign-declare "extern int callout(int, int, int);"))
        
        (define callout (foreign-callback-lambda int "callout" int int int))
        
        (define-external (callin (scheme-object xyz)) int
          (print "This is 'callin': " xyz)
          123)
        
        (print (callout 1 2 3))
        
        % cat bar.c
        #include <stdio.h>
        #include "chicken.h"
        
        extern int callout(int, int, int);
        extern int callin(C_word x);
        
        int callout(int x, int y, int z)
        {
          C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
          C_word lst;
        
          printf("This is 'callout': %d, %d, %d\n", x, y, z);
          lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
          return callin(lst);
        }
        
        % chicken foo.scm -output-file foo.c -quiet
        % gcc foo.c bar.c -o foo `chicken-config -cflags -libs`
        % foo
        This is 'callout': 1, 2, 3
        This is 'callin': (1 2 3)
        123
        

        Notes:

        • Scheme procedures can call C functions, and C functions can call Scheme procedures, but for every pending C stack frame, the available size of the first heap generation (the "nursery") will be decreased, because the C stack is identical to the nursery. On systems with a small nursery this might result in thrashing, since the C code between the invocation of C from Scheme and the actuall calling back to Scheme might build up several stack-frames or allocates large amounts of stack data. To prevent this it is advisable to increase the default nursery size, either when compiling the file (using the -nursery option) or when running the executable (using the -:s runtime option).
        • Calls to Scheme/C may be nested arbitrarily, and Scheme continuations can be invoked as usual, but keep in mind that C stack frames will not be recovered, when a Scheme procedure call from C does not return normally.
        • When multiple threads are running concurrently, and control switches from one thread to another, then the continuation of the current thread is captured and saved. Any pending C stack frame still active from a callback will remain on the stack until the threads is re-activated again. This means that in a multithreading situation, when C callbacks are involved, the available nursery space can be smaller than expected. So doing many nested Scheme->C->Scheme calls can reduce the available memory up to the point of thrashing. It is advisable to have only a single thread with pending C stack-frames at any given time.
        • Pointers to Scheme data objects should not be stored in local or global variables while calling back to Scheme. Any Scheme object not passed back to Scheme will be reclaimed or moved by the garbage collector.
        • Calls from C to Scheme are never tail-recursive.
        • Continuations captured via call-with-current-continuation and passed to C code can be invoked like any other Scheme procedure.

    7. Parameters:

      Certain behaviour of the interpreter and compiled programs can be customized via 'parameters', where a parameter is a procedure of zero or one arguments. To retrieve the value of a parameter call the parameter-procedure with zero arguments. To change the setting of the parameter, call the parameter-procedure with the new value as argument:

      (define foo (make-parameter 123))
      (foo)                             ==> 123
      (foo 99)
      (foo)                             ==> 99
      

      (See also: make-parameter and parameterize)

      [parameter] case-sensitive
      If true, then read reads symbols and identifiers in case-sensitive mode and uppercase characters in symbols are printed escaped.
      [parameter] command-line-arguments
      When the interpreter (csi) is invoked with the -script option, or when a script is compiled, then this parameter contrains the list of arguments passed to the script, with the script name removed.
      [parameter] error-handler
      A procedure of one or more arguments that is called when an error occurs. The default behaviour is to display the first argument and write any other arguments to the port that is the value of (current-error-port). Returning normally from an error-handler will kill all threads but the primordial one and invoke the value of (reset-handler).
      [parameter] exit-handler
      A procedure of a single optional argument. When exit is called, then this procedure will be invoked with the exit-code as argument. The default behaviour is to terminate the program.
      [parameter] eval-handler
      A procedure of one or two arguments. When eval is invoked, it calls the value of this parameter with the same arguments. The default behaviour is to evaluate the argument expression and to ignore the second parameter.
      [parameter] implicit-exit-handler
      A procedure of no arguments. When the last toplevel expression of the program has executed, then the value of this parameter is called. The default behaviour is to do nothing, or, if one or more entry-points were defined (see: Entry points) to enter a loop that waits for callbacks from the host program.
      [parameter] reset-handler
      A procedure of zero arguments that is called via reset. The default behaviour in compiled code is to invoke the value of (exit-handler). The default behaviour in the interpreter is to abort the current computation and to restart the read-eval-print loop.

    8. The module system

      Terminology:
      A unit names a single unit of compilation. Each unit of compilation is translated to a single C file by the compiler and normally results in a single object module that will be linked resulting in a library or a standalone executable.
      A module designates a namespace, which maps names to symbols. The same name can have different meanings in different modules. Similarly named objects can coexist in separate modules. A module may consist of several source files, but a module can not include more than on compilation unit.

      In normal mode the compiler and interpreter do not enforce any specific module discipline. All global symbols exist in the same flat namespace. The define-module form can be used to evaluate or compile files in a namespace separate from this flat global namespace.

      [syntax] (define-module NAME CLAUSE ...)
      Defines or redefines a module with the name NAME. Any previous definition of a module with the same name will be overwritten. Each CLAUSE specifies additional properties of the module:
      [module clause] (export SYMBOL ...)
      Makes SYMBOL ... exported symbols of this module, which can be externally referenced.
      [module clause] (import (MODULE IMPORT ...) ...)
      Imports exported bindings from MODULE. IMPORT can be a symbol or a list of the form (SYMBOL ALIAS). When an alias is specified, the symbol can be accessed under this alias instead of the originally exported name SYMBOL.
      If the list of imported symbols is empty, then all exported bindings of the given module are imported, and that module must have been defined previously. If the list is non-empty, then forward imports (imports of modules defined at a later stage) are allowed.
      As an alternative to (import (MODULE)), the syntax (import MODULE) is allowed.
      [module clause] (import-excluding (MODULE EXCLUDE ...) ...)
      Imports bindings from MODULE that are not given in EXCLUDE .... (import-excluding (MODULE)) is in every aspect equivalent to (import (MODULE)).
      [module clause] (files FILENAME ...)
      Defines source files to be processed inside the namespace of this module. The files clause will be accessed using the include form, so the current include path will be respected. During processing of the files, the feature identifier use-modules is registered (for use in cond-expand).
      [module clause] (begin EXPRESSION ...)
      Process toplevel forms EXPRESSION ... inside the namespace of the current module. For larger pieces of code the files clause might be more suitable. Forms given by this clause type and forms included from files are processed in exactly the same order as they appear in the module definition.
      [module clause] (unit UNITNAME)
      Defines a library unit which should be used when this module is imported. UNITNAME must be a symbol. This is useful for module definitions without files clauses, that only specify the bindings exported by an already existing library.
      If a module definition contains this clause and also one ore more files or begin clauses, then it is assumed that the current compilation unit designates a libary unit, and a (declare (unit UNITNAME)) declaration is generated.

      Predefined modules in the CHICKEN system are:

        scheme
        Contains all names as defined in R5RS.
        Note that to do anything useful, the scheme module should be imported.
        syntax-case
        Macros and functions used in the syntax-case macro system.
        chicken-library
        Non-standard extensions to Scheme as defined in the CHICKEN library.
        chicken-extras
        Non-standard extensions as defined in the CHICKEN utility library (unit extras).
        chicken-lolevel
        Non-standard extensions as defined in the low-level utility library (unit lolevel).
        chicken-unistd
        Definitions from the unistd UNIX interface.
        chicken-regex
        Definitions from the regex regular expression library.
        chicken-ffi
        All definitions for accessing foreign code or variables. This includes define-entry-point, define-external and all foreign type specifiers.
        srfi-1
        srfi-4
        srfi-13
        srfi-14 or char-set-lib
        srfi-18
        format
        match
        debugger
        tinyclos
        Definitions from the corresponding library units. Importing from any of these modules will automatically declare the associated library unit as used
        (as in (declare (uses UNIT))).
        string-lib
        string-lib-internals
        The SRFI-13 modules (as recommended in the spec). Note that the srfi-13 module exports the bindings of both string-lib and string-lib-internals.

      An example: Consider the following source file

      ;;; foo.scm
      
      (define-module bar
        (export hello)
        (import (scheme))
        (begin
          (define (hello s)
            (string-append "Hello, " s "!") ) ) )
      
      (define-module foo
        (import (bar)
      	  (scheme)
      	  (chicken-library)
      	  (chicken-extras (string-concatenate conc))
      	  (srfi-13) )
        (begin
          (print (conc (map hello '("one" "two" "three")) "\n")) ) )
      

      Here we have a single compilation unit that contains the two modules foo and bar. bar exports the symbol hello. The module foo imports bindings from bar and some other modules. The modules chicken-extras and srfi-13 both export a binding for the symbol string-concatenate. Here we use conc as an alias to the binding in extras.

      Compiling the file foo.scm yields:

        % chicken foo.scm -quiet -output-file foo.c
        % gcc foo.c `chicken-config -cflags -libs -extra-libs` -o foo
        % foo
        Hello, one!
        Hello, two!
        Hello, three!
      

      Module definitions may not be nested and can be interpreted or compiled, but are not available in code that is evaluated explicitly with eval. To use modules, all code has to be wrapped into module definition forms, either directly (using begin clauses) or indirectly (using files clauses).

      To use the module system with separately compiled library units, the following convenience macros can be used:

      [syntax] (define-library-implementation NAME CLAUSE ...)
      Defines a module that will be compiled to a separate library unit. This form is syntactic sugar for
      (define-module NAME (unit NAME) CLAUSE ...)
      [syntax] (define-library-interface NAME EXPORT1 ...)
      Defines an interface to a separately compiled library unit. This form is syntactic sugar for
      (define-module NAME (unit NAME) (export EXPORT1 ...))

      As an example, consider these two source files

      ;;; bar.scm
      
      (define-library-implementation bar
        (import (scheme))
        (begin
          (define (hello s)
            (string-append "Hello, " s "!") ) ) )
      
      
      ;;; foo.scm
      
      (define-library-interface bar
        hello)
      
      (define-module foo
        (import (bar)
      	  (scheme)
      	  (chicken-library)
      	  (chicken-extras (string-concatenate conc))
      	  (srfi-13) )
        (begin
          (print (conc (map hello '("one" "two" "three")) "\n")) ) )
      

      Both files are separately compiled:

        % chicken foo.scm -quiet -output-file foo.c
        % chicken bar.scm -quiet -explicit-use -output-file bar.c
        % gcc -c bar.c `chicken-config -cflags` -o bar.o
        % gcc foo.c bar.o `chicken-config -cflags -libs -extra-libs` -o foo
        % foo
        Hello, one!
        Hello, two!
        Hello, three!
      

      Note that the interface definitions of library modules have to be given in any module definition file that imports those libraries. The interfaces of builtin library modules like chicken-library are defined automatically, but for your own libraries it is helpful to have a central "repository" for interface definitions. This is accomplished by the file .chicken-interfaces. Whenever module definitions are encountered, this file is loaded from either the current HOME directory or the directory given in the environment variable CHICKEN_HOME, if it exists.

    9. Unit: library

      This unit contains basic Scheme definitions. This unit is used by default, unless the executable is compiled with the -explicit-use option.

      1. Arithmetic:
        [procedure] (add1 N)
        [procedure] (sub1 N)
        Adds/subtracts 1 from N.
        [procedure] (bitwise-and N1 N2)
        [procedure] (bitwise-ior N1 N2)
        [procedure] (bitwise-xor N1 N2)
        [procedure] (bitwise-not N)
        [procedure] (arithmetic-shift N1 N2)
        Binary fixnum operations. arithmetic-shift shifts the argument N1 by N2 bits to the left. If N2 is negative, than N1 is shifted to the right.
        [procedure] (fixnum? X)
        Returns #t if X is a fixnum, or #f otherwise.
        [procedure] (fx+ N1 N2)
        [procedure] (fx- N1 N2)
        [procedure] (fx* N1 N2)
        [procedure] (fx/ N1 N2)
        [procedure] (fxmod N1 N2)
        [procedure] (fxneg N)
        [procedure] (fxmin N1 N2)
        [procedure] (fxmax N1 N2)
        [procedure] (fx= N1 N2)
        [procedure] (fx> N1 N2)
        [procedure] (fx< N1 N2)
        [procedure] (fx>= N1 N2)
        [procedure] (fx<= N1 N2)
        Arithmetic fixnum operations. These procedures do not check their arguments, so non-fixnum parameters will result in incorrect results. fxneg negates its argument.
        [procedure] (signum N)
        Returns 1 if N is positive, -1 if N is negative or 0 if N is zero.

      2. Input/Output:
        [procedure] (current-error-port)
        Returns default error output port.
        [procedure] (end-of-file)
        Returns the end-of-file object.
        [procedure] (flush-output [PORT])
        Write buffered output to the given output-port. PORT defaults to the value of (current-output-port).
        [procedure] (port-name PORT)
        Fetch filename from PORT. This returns the filename that was used to open this file. Returns a special tag string, enclosed into parantheses for non-file ports.
        [procedure] (port-position PORT)
        Returns the current position of PORT as two values: row and column number. If the port does not support such an operation an error is signaled. This procedure is currently only available for input ports.

      3. Files:
        [procedure] (delete-file STRING)
        Deletes the file with the pathname STRING. If the file does not exist, an error is signaled.
        [procedure] (file-exists? STRING)
        Returns #t if a file with the given pathname exists, or #f otherwise.
        [variable] pathname-directory-separator
        Contains the directory-separator character for pathnames on this platform.
        [variable] pathname-extension-separator
        Contains the extension-separator character for pathnames on this platform.
        [procedure] (rename-file OLD NEW)
        Renames the file or directory with the pathname OLD to NEW. If the operation does not succeed, an error is signaled.

      4. String ports:
        [procedure] (get-output-string PORT)
        Returns accumulated output of a port created with (open-output-string).
        [procedure] (open-input-string STRING)
        Returns a port for reading from STRING.
        [procedure] (open-output-string)
        Returns a port for accumulating output in a string.
        [procedure] (print-to-string EXP ...)
        Displays EXP on string port and returns the result string.

      5. Feature identifiers
        [procedure] (features)
        Returns a list of all registered features that will be accepted as valid feature-identifiers by cond-expand.
        [procedure] (register-feature! FEATURE ...)
        Register one or more features that will be accepted as valid feature-identifiers by cond-expand. FEATURE ... may be a keyword, string or symbol.
        [procedure] (unregister-feature! FEATURE ...)
        Unregisters the specified feature-identifiers. FEATURE ... may be a keyword, string or symbol.

      6. Keywords

        Keywords are special symbols prefixed with #: that evaluate to themselves. Procedures can use keywords to accept optional named parameters in addition to normal required parameters.
        Assignment to and bindings of keyword symbols is not allowed.

        [procedure] (get-keyword KEYWORD ARGLIST [THUNK])
        Returns the argument from ARGLIST specified under the keyword KEYWORD. If the keyword is not found, then the zero-argument procedure THUNK is invoked and the result value is returned. If THUNK is not given, #f is returned.
        (define (increase x . args)
          (+ x (get-keyword args #:amount (lambda () 1))) )
        (increase 123)                                      ==> 124
        (increase 123 #:amount 10)                          ==> 133
        
        [procedure] (keyword? X)
        Returns #t if X is a keyword symbol, or #f otherwise.
        [procedure] (keyword->string KEYWORD)
        Transforms KEYWORD into a string.
        [procedure] (string->keyword STRING)
        Returns a keyword with the name STRING.

      7. Exceptions CHICKEN implements the (currently withdrawn) SRFI-12 exception system. For more information, see the SRFI-12 Document.

        Notes:

        • All error-exceptions (of the kind exn are non-continuable.
        • Error-exceptions of the exn kind have an additional arguments property that contains the arguments passed to the error-handler.
        • When the unistd unit is available and used, then a user-interrupt (signal/int) signals an exception of the kind user-interrupt.

      8. Miscellaneous:
        [procedure] (argv)
        Return a list of all supplied command-line arguments. The first item in the list is a string containing the name of the executing program. The other items are the arguments passed to the application. This list is freshly created on every invocation of (argv). It depends on the host-shell wether arguments are expanded ('globbed') or not.
        [procedure] (char-name SYMBOL-OR-CHAR [CHAR])
        This procedure can be used to inquire about character names or to define new ones. With a single argument the behaviour is as follows:
        If SYMBOL-OR-CHAR is a symbol, then char-name returns the character with this name, or #f if no character is defined under this name.
        If SYMBOL-OR-CHAR is a character, then the name of the character is returned as a symbol, or #f if the character has no associated name.

        If the optional argument CHAR is provided, then SYMBOL-OR-CHAR should be a symbol that will be the new name of the given character.
        If multiple names designate the same character, then the write will use the character name that was defined last.

        (char-name 'space)                  ==> #\space
        (char-name #\space)                 ==> space
        (char-name 'bell)                   ==> #f
        (char-name (integer->char 7))       ==> #f
        (char-name 'bell (integer->char 7))
        (char-name 'bell)                   ==> #\bell
        (char->integer (char-name 'bell))   ==> 7
        
        [procedure] (current-milliseconds)
        Returns the number of milliseconds since process- or machine startup.
        [procedure] (current-seconds)
        Returns the number of seconds since midnight, Jan. 1, 1970.
        [procedure] (enable-interrupts)
        [procedure] (disable-interrupts)
        Enables/disables processing of timer-interrupts and interrupts caused by signals.
        (disable-interrupts)
        (disable-interrupts)
        (enable-interrupts)
        ; <interupts still disabled - call enable-interrupts once more>
        
        [procedure] (errno)
        Returns the error code of the last system call.
        [procedure] (error STRING EXP ...)
        Prints error message, writes all extra arguments to the value of (current-error-port) and invokes the current value of (error-handler). This conforms to SRFI-23.
        [procedure] (exit [CODE])
        Exit the running process and return exit-code, which defaults to 0 (Invokes exit-handler).
        [procedure] (gc [FLAG])
        Invokes a garbage-collection and returns the number of free bytes in the heap. The flag specifies wether a minor (#f) or major (#t) GC is to be triggered. If no argument is given, #t is assumed.
        [procedure] (gensym [STRING-OR-SYMBOL])
        Returns a newly created uninterned symbol. If an argument is provided, the new symbol is prefixed with that argument.
        [procedure] (getenv STRING)
        Returns the value of the environment variable STRING or #f if that variable is not defined.
        [procedure] (machine-type)
        Returns a symbol specifying the processor on which this process is currently running.
        [procedure] (make-parameter VALUE [GUARD])
        Returns a procedure that accepts zero or one argument. Invoking the procedure with zero arguments returns VALUE. Invoking the procedure with one argument changes it's value to the value of that argument (subsequent invocations with zero parameters return the new value). GUARD should be a procedure of a single argument. Any new values of the parameter (even the initial value) are passed to this procedure. The guard procedure should check the value and/or convert it to an appropriate form.
        [procedure] (port? X)
        Returns #t if X is a port object or #f otherwise.
        [procedure] (print EXP1 ...)
        Outputs the arguments EXP1, ... using display and writes a newline character to the port that is the value of (current-output-port).
        [procedure] (print* EXP1 ...)
        Similar to print, but does not output a terminating newline character.
        [procedure] (reset)
        Reset program (Invokes reset-handler).
        [procedure] (set-finalizer! X PROC)
        Registers a procedure of one argument PROC, that will be called as soon as the non-immediate data object X is about to be garbage-collected (with that object as it's argument).
        Note that the finalizer will not be called when interrupts are disabled.
        [procedure] (set-gc-report! FLAG)
        Print statistics after every GC, depending on FLAG. A value of #t shows statistics after every major GC. A value true value different from #t shows statistics after every minor GC. #f switches statistics off.
        [procedure] (software-type)
        Returns a symbol specifying the operasting system on which this process is currently running.
        [procedure] (string->uninterned-symbol STRING)
        Returns a newly created, unique symbol with the name STRING.
        [procedure] (system STRING)
        Execute shell command. The functionality offered by this procedure depends on the capabilities of the host shell.
        [procedure] (vector-copy! VECTOR1 VECTOR2 [COUNT])
        Copies contents of VECTOR1> into VECTOR2. If the argument COUNT is given, it specifies the maximal number of elements to be copied.
        [procedure] (void)
        Returns an unspecified value.

    10. Unit: eval

      This unit has support for evaluation and macro-handling. This unit is used by default, unless the executable is compiled with the -explicit-use option.

      1. Expression evaluation:
        [procedure] (eval EXP [ENVIRONMENT])
        Evaluates EXP and returns the result of the evaluation. The second arguments is always ignored.
        [procedure] (load FILENAME [EVALPROC])
        Loads and evaluates expressions from the given source file. Each expression read is passed to EVALPROC (which defaults to eval).
        [procedure] (load-noisily FILENAME [EVALPROC])
        As load but the result(s) of each evaluated toplevel-expression is written to standard output.
        [procedure] (load-srfi-7-program FILENAME [EVALPROC])
        Loads and evaulates expressions that are specified as a SRFI-7 configuration language program.

      2. Read-eval-print loop:
        [procedure] (read-eval-print-loop)
        Start a new read-eval-print loop. Sets the reset-handler so that any invocation of reset restarts the read-eval-print loop. Also changes the current error-handler to display a message, write any arguments to the value of (current-error-port) and reset.

      3. Macros:
        [procedure] (get-line-number EXPR)
        If EXPR is a pair with the car being a symbol, and line-number information is available for this expression, then this procedure returns the associated line number. If line-number information is not available, then #f is returned. Note that line-number information for expressions is only available in the compiler.
        [procedure] (macro? SYMBOL)
        Returns #t if there exists a macro-definition for SYMBOL.
        [procedure] (macroexpand X)
        If X is a macro-form, expand the macro (and repeat expansion until expression is a non-macro form). Returns the resulting expression.
        [procedure] (macroexpand-1 X)
        If X is a macro-form, expand the macro. Returns the resulting expression.
        [procedure] (undefine-macro! SYMBOL)
        Remove the current macro-definition of the macro named SYMBOL.

      4. Miscellaneous:
        [procedure] (define-reader-ctor SYMBOL PROC)
        Define new read-time constructor for #, read syntax. For further information, see documentation for SRFI-10.

    11. Unit: debugger

      This unit provides an interactive debugger. When compiling with the -emit-debug-info option, then the debugger unit is automatically declared as used. Any errors will enter the debugger's read-eval-print loop. To enter a break-loop as soon as the executable starts, invoke the compiled program with the -:b runtime option.

      [procedure] (break [MESSAGE])
      Enters the debugger. If MESSAGE is provided, then it should be either a string or #f. For a list of available debugger commands enter ?.

    12. Unit: extras

      This unit contains a collection of useful utility definitions.

      1. Lists:
        [procedure] (butlast LIST)
        Returns a fresh list with all elements but the last of LIST.
        [procedure] (chop LIST N)
        Returns a new list of sublists, where each sublist contains N elements of LIST. If LIST has a length that is not a multiple of N, then the last sublist contains the remaining elements.
        (chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))
        (chop '(a b c d) 3)     ==> ((a b c) (d))
        
        [procedure] (compress BLIST LIST)
        Returns a new list with elements taken from LIST with corresponding true values in the list BLIST.
        (define nums '(99 100 110 401 1234))
        (compress (map odd? nums) nums)      ==> (99 401)
        
        [procedure] (flatten LIST1 ...)
        Returns LIST1 ... concatenated together, with nested lists removed (flattened).
        [procedure] (intersperse LIST X)
        Returns a new list with X placed between each element.
        [procedure] (tail? X LIST)
        Returns true if X is one of the tails (cdr's) of LIST.

      2. String-port extensions:
        [procedure] (call-with-input-string STRING PROC)
        Calls the procedure PROC with a single argument that is a string-input-port with the contents of STRING.
        [procedure] (call-with-output-string PROC)
        Calls the procedure PROC with a single argument that is a string-output-port. Returns the accumulated output-string.
        [procedure] (with-input-from-string STRING THUNK)
        Call procedure THUNK with the current input-port temporarily bound to an input-string-port with the contents of STRING.
        [procedure] (with-output-to-string THUNK)
        Call procedure THUNK with the current output-port temporarily bound to a string-output-port and return the accumulated output string.

      3. Formatted output:
        [procedure] (fprintf PORT FORMATSTRING ARG ...)
        [procedure] (printf FORMATSTRING ARG)
        [procedure] (sprintf FORMATSTRING ARG ...)
        Simple formatted output to a given port (fprintf), the value of (current-output-port) (printf) or a string (sprintf). The FORMATSTRING can contain any sequence of characters. The character '~' prefixes special formatting directives:
        ~% write newline character
        ~S write the next argument
        ~A display the next argument
        ~\n skip all whitespace in the format-string until the next non-whitespace character
        ~B write the next argument as a binary number
        ~O write the next argument as an octal number
        ~X write the next argument as a hexadecimal number
        ~C write the next argument as a character
        ~~ display '~'
        ~! flush all pending output
        ~? invoke formatted output routine recursively with the next two arguments as format-string and list of parameters

      4. Hash tables:
        [procedure] (clear-hash-table! HASH-TABLE)
        Erases all entries in the hash-table HASH-TABLE.
        [procedure] (get HASH-TABLE KEY PROP)
        Returns the value of property PROP of the item KEY in HASH-TABLE . This facility can be used as a kind of "disembodied" property-list. If no entry named KEY is stored in the hash-table or if no property PROP for that key exists, #f is returned.
        [procedure] (hash-table? X)
        Returns #t if the argument is a hash-table.
        [procedure] (hash-table-count HASH-TABLE)
        Returns the number of entries in the given hash-table.
        [procedure] (hash-table-for-each PROC HASH-TABLE)
        Calls PROC which should expect two arguments. This procedure is called for each entry in the hash-table with the key and the value as parameters.
        [procedure] (hash-table-ref HASH-TABLE KEY [DEFAULT])
        Returns the entry in the given hash-table under KEY. If no entry is stored in the table, #f is returned.
        [procedure] (hash-table-set! HASH-TABLE KEY VALUE)
        Adds or changes an entry in the given hash-table.
        [procedure] (make-hash-table [SIZE])
        Creates and returns a hash-table with keys compared via eq?. If SIZE is provided it specifies the initial size of the hash-table. If the hash-table fills above a certain size it is automatically resized to accommodate more entries.
        [procedure] (put! HASH-TABLE KEY PROP VALUE)
        Stores VALUE as property PROP under the item KEY in the given hash-table. Any previously existing value is overwritten.

      5. Queues:
        [procedure] (list->queue LIST)
        Returns LIST converted into a queue, where the first element of the list is the same as the first element of the queue. The resulting queue may share memory with the list and the list should not be modified after this operation.
        [procedure] (make-queue)
        Returns a newly created queue.
        [procedure] (queue? X)
        Returns #t if X is a queue, or #f otherwise.
        [procedure] (queue->list QUEUE)
        Returns QUEUE converted into a list, where the first element of the list is the same as the first element of the queue. The resulting list may share memory with the queue object and should not be modified.
        [procedure] (queue-add! QUEUE X)
        Adds X to the rear of QUEUE.
        [procedure] (queue-empty? QUEUE)
        Returns #t if QUEUE is empty, or #f otherwise.
        [procedure] (queue-first QUEUE)
        Returns the first element of QUEUE. If QUEUE is empty an error is signaled
        [procedure] (queue-last QUEUE)
        Returns the last element of QUEUE. If QUEUE is empty an error is signaled
        [procedure] (queue-remove! QUEUE)
        Removes and returns the first element of QUEUE. If QUEUE is empty an error is signaled

      6. Sorting:
        [procedure] (merge LIST1 LIST2 LESS?) 
        [procedure] (merge! LIST1 LIST2 LESS?)
        Joins two lists in sorted order. merge! is the destructive version of merge. LESS? should be a procedure of two arguments, that returns true if the first argument is to be ordered before the second argument.
        [procedure] (sort SEQUENCE LESS?)	
        [procedure] (sort! SEQUENCE LESS?)
        Sort SEQUENCE, which should be a list or a vector. sort! is the destructive version of sort.
        [procedure] (sorted? SEQUENCE LESS?)
        Returns true if the list or vector SEQUENCE is already sorted.

      7. Random numbers:
        [procedure] (random N)
        Returns an exact random integer from 0 to N-1.
        [procedure] (randomize [X])
        Set random-number seed. If X is not supplied, the current time is used.

      8. Input/Output extensions:
        [procedure] (make-input-port READ READY? CLOSE [PEEK])
        Returns a custom input port. Common operations on this port are handled by the given parameters, which should be procedures of no arguments. READ is called when the next character is to be read and should return a character or the value of (end-of-file). READY? is called when char-ready? is called on this port and should return #t or #f. CLOSE is called when the port is closed. PEEK is called when peek-char is called on this port and should return a character or the value of (end-of-file). if the argument PEEK is not given, then READ is used instead and the created port object handles peeking automatically (by calling READ and buffering the character).
        [procedure] (make-output-port WRITE CLOSE)
        Returns a custom output port. Common operations on this port are handled by the given parameters, which should be procedures. WRITE is called when output is sent to the port and receives a single argument, a string. CLOSE is called when thje port is closed and should be a procedure of no arguments.
        [procedure] (pretty-print EXP [PORT])
        Print expression nicely formatted. PORT defaults to the value of (current-output-port).
        [parameter] pretty-print-width
        Specifies the maximal line-width for pretty printing, after which line wrap will occur.
        [procedure] (read-file [PORT])
        Returns a list containing all toplevel expressions read from PORT, which defaults to the value of (current-input-port).
        [procedure] (read-line [PORT])
        [procedure] (write-line STRING [PORT])
        Line-input and -output. PORT defaults to the value of (current-input-port) and (current-output-port), respectively.
        [procedure] (read-lines [PORT [MAX]])
        Read MAX or fewer lines from PORT. PORT defaults to the value of (current-input-port).
        [procedure] (read-string NUM [PORT])
        Read NUM characters from PORT, which defaults to the value of (current-input-port). The characters are returned as a string of length NUM or less, if the port contains fewer than NUM characters.
        [procedure] (with-error-output-to-port PORT THUNK)
        Call procedure THUNK with the current error output-port temporarily bound to PORT.
        [procedure] (with-input-from-port PORT THUNK)
        Call procedure THUNK with the current input-port temporarily bound to PORT.
        [procedure] (with-output-to-port PORT THUNK)
        Call procedure THUNK with the current output-port temporarily bound to PORT.

      9. Strings:
        [procedure] (string-any PROC STRING1 STRING2 ...)
        Apply PROC on every Nth element of the argument strings and return the first result that is true, or #f if no application returned true.
        [procedure] (string-capitalize STRING)
        Returns a new string with the words in the argument STRING capitalized.
        [procedure] (string-capitalize! STRING)
        Capitalizes words in the argument STRING and returns the modified string.
        [procedure] (string-concatenate LIST [STRING])
        Returns a string that contains all strings in LIST concatenated together. If the second parameter STRING is provided, then it is placed between each concatenated string.
        (string-concatenate '("one" "two") "three") <=> (apply string-append (intersperse '("one" "two") "three"))
        [procedure] (string-filter PROC STRING)
        Returns a new string with characters filtered out of STRING. PROC should take one argument and return #f if that argument is not to be accumulated in the result string.
        [procedure] (string-downcase STRING)
        [procedure] (string-upcase STRING)
        Convert string to uppercase or lowercase.
        [procedure] (string-downcase! STRING)
        [procedure] (string-upcase! STRING)
        Destructive versions of the functions above.
        [procedure] (string-every PROC STRING1 STRING2 ...)
        Apply PROC on every Nth element of the argument strings. If all results are true, return the last one. If no result was true, return #f.
        [procedure] (string-index PROC STRING1 STRING2 ...)
        Returns first index i where PROC applied to the elements of STRING1, STRING2 ... at position i is true.
        [procedure] (string-trim STRING TRIMCHARS)
        [procedure] (string-left-trim STRING TRIMCHARS)
        [procedure] (string-right-trim STRING TRIMCHARS)
        Return new copy of STRING with all characters in the string TRIMCHARS removed from the left/right side(s).
        [procedure] (string-map PROC STRING1 STRING2 ...)
        [procedure] (string-map! PROC STRING1 STRING2 ...)
        Map over characters in one or more strings and return the first string (or a copy in the case of string-map) where each character is replaced with the result of the procedure.
        [procedure] (string-reverse STRING)
        [procedure] (string-reverse! STRING)
        Reverse characters in STRING. string-reverse! is the destructive version.
        [procedure] (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
        Split string into substrings separated by the given delimiters. If no delimiters are specified, "\t\n " is assumed. If the parameter KEEPEMPTY is given and not #f, then empty substrings are retained:
        (string-split "one  two  three") ==> ("one" "two" "three")
        (string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "")
        
        [procedure] (string-translate STRING FROM [TO])
        Returns a fresh copy of STRING with characters matching FROM translated to TO. If TO is omitted, then matching characters are removed. FROM and TO may be a character, a string or a list. If both FROM and TO are strings, then the character at the same position in TO as the matching character in FROM is substituted.
        [procedure] (substring-index WHICH WHERE [START])
        [procedure] (substring-index-ci WHICH WHERE [START])
        Searches for first index in string WHERE where string WHICH occurs. If the optional argument START is given, then the search starts at that index.
        substring-index-ci is a case-insensitive version of substring-index.

      10. Miscellaneous:
        [procedure] (constantly X)
        Returns a procedure that always returns X regardless of the number and value of its arguments.
        (constantly X) <=> (lambda args X)
        [procedure] (complement PROC)
        Returns a procedure that returns the boolean inverse of PROC.
        (complement PROC) <=> (lambda (x) (not (PROC x)))
        [procedure] (compose PROC1 PROC2 ...)
        Returns a procedure that represents the composition of the argument-procedures PROC1 PROC2 ....
        (compose F G) <=> (lambda args (call-with-values (lambda () (apply G args)) F))
        [procedure] (flip PROC)
        Returns a two-argument procedure that calls PROC with its arguments swapped:
        (flip PROC) <=> (lambda (x y) (PROC y x))

    13. Unit: srfi-1

      List library, see documentation for SRFI-1

    14. Unit: srfi-4

      Homogeneous numeric vectors, see documentation for SRFI-4. In addition to that, the following procedures are also provided:

      [procedure] (u8vector->byte-vector U8VECTOR)
      [procedure] (s8vector->byte-vector S8VECTOR)
      [procedure] (u16vector->byte-vector U16VECTOR)
      [procedure] (s16vector->byte-vector S16VECTOR)
      [procedure] (u32vector->byte-vector U32VECTOR)
      [procedure] (s32vector->byte-vector S32VECTOR)
      [procedure] (f32vector->byte-vector F32VECTOR)
      [procedure] (f64vector->byte-vector F64VECTOR)
      Each of these procedures return the contents of the given vector as a 'packed' byte-vector. The byte order in that vector is platform-dependent (for example little-endian on an Intel processor). The returned byte-vector shares memory with the contents of the vector.
      [procedure] (byte-vector->u8vector BYTE-VECTOR)
      [procedure] (byte-vector->s8vector BYTE-VECTOR)
      [procedure] (byte-vector->u16vector BYTE-VECTOR)
      [procedure] (byte-vector->s16vector BYTE-VECTOR)
      [procedure] (byte-vector->u32vector BYTE-VECTOR)
      [procedure] (byte-vector->s32vector BYTE-VECTOR)
      [procedure] (byte-vector->f32vector BYTE-VECTOR)
      [procedure] (byte-vector->f64vector BYTE-VECTOR)
      Each of these procedures return a vector where the argument BYTE-VECTOR is taken as a 'packed' representation of the contents of the vector. The argument-byte-vector shares memory with the contents of the vector.

    15. Unit: srfi-13

      String library, see documentation for SRFI-13
      (This library unit can be loaded in the interpreter csi using include or load).

    16. Unit: srfi-14

      Character set library, see documentation for SRFI-14
      (This library unit can be loaded in the interpreter csi using include or load).

      • This library provides only the Latin-1 character set.

    17. Unit: match

      Andrew Wright's pattern matching package.

      [syntax] (match EXP CLAUSE ...)
      [syntax] (match-lambda CLAUSE ...)
      [syntax] (match-lambda* CLAUSE ...)
      [syntax] (match-let ((PAT EXP) ...) BODY)
      [syntax] (match-let* ((PAT EXP) ...) BODY)
      [syntax] (match-letrec ((PAT EXP) ...) BODY)
      [syntax] (match-define PAT EXP)
      Match expression or procedure arguments with pattern and execute associated expressions. You can download a Postscript manual here.
      [syntax] (define-structure (ID_0 ID_1 ... ID_N))
      [syntax] (define-structure (ID_0 ID_1 ... ID_N) ((ID_{N+1} EXP_1) ... (ID_{N+M} EXP_M)))
      [syntax] (define-const-structure (ID_0 ARG_1 ... ARG_N))
      [syntax] (define-const-structure (ID_0 ARG_1 ... ARG_N) ((ARG_{N+1} EXP_1) ... (ARG_{N+M} EXP_M)))
      Macros for defining record structures that can be decomposed by match.
      (match-error-control [MODE])
      Selects a mode that specifies how match... macro forms are to be expanded. With no argument this procedure returns the current mode. A single argument specifies the new mode that decides what should happen if no match-clause applies.
      The following modes are supported:
      #:error
      Signal an error. This is the default.
      #:match
      Signal an error and output the offending form.
      #:fail
      Omits pair? tests when the consequence is to fail in car or cdr rather than to signal an error.
      #:unspecified
      Non-matching expressions will either fail in car or cdr or return an unspecified value.
      This mode applies to files compiled with the unsafe option or declaration.

    18. Unit: regex

      When the GNU regex 0.12 package is available, then this unit provides some useful procedures for working with regular expressions. See the GNU documentation for detailed information about regular expression syntax. The selected syntax bits are: RE_INTERVALS, RE_NO_BK_BRACES, RE_NO_BK_PARENS, RE_NO_BK_VBAR.

      [procedure] (grep REGEX LIST)
      Returns all items of LIST that match the regular expression REGEX. This procedure could be defined as follows:
      (define (grep regex lst)
        (filter (lambda (x) (string-match regex x)) lst) )
      
      [procedure] (pattern->regexp PATTERN)
      Converts the file-pattern PATTERN into a regular expression.
      (pattern->regexp "foo.*") ==> "^foo\\..*$"
      
      [procedure] (string-match REGEXP STRING [START])
      [procedure] (string-match-positions REGEXP STRING [START])
      Matches the regular expression in string REGEXP with STRING and returns either #f if the match failed, or a list of matching groups, where the first element is the complete match. If the optional argument START is supplied, it specifies the starting position in STRING. For each matching group the result-list contains either: #f for a non-matching but optional group; a list of start- and end-position of the match in STRING (in the case of string-match-positions); or the matching substring (in the case of string-match).
      [procedure] (string-search REGEXP STRING [START [RANGE]])
      [procedure] (string-search-positions REGEXP STRING [START [RANGE]])
      Searches for the first match of the regular expression in string REGEXP with STRING. The search can be limited to RANGE characters. Otherwise the procedures have the same behaviour as string-match / string-match-positions.
      [procedure] (string-split-fields REGEXP STRING [MODE [START]])
      Splits STRING into a list of fields according to MODE, where MODE can be the keyword #:infix (REGEXP matches field separator), the keyword #:suffix (REGEXP matches field terminator) or #t (REGEXP matches field), which is the default.
      [procedure] (string-substitute REGEXP SUBST STRING [INDEX])
      Searches substrings in STRING that match REGEXP and substitutes them with the string SUBST. The substitution can contain references to subexpressions in REGEXP with the \NUM notation, where NUM refers to the NUMth parenthesized expression. The optional argument INDEX defaults to 1 and specifies the number of the match to be substituted. Any non-numeric index specifies that all matches are to be substituted.
      (string-substitute "([0-9]+) (eggs|chicks)" "\\2 (\\1)" "99 eggs or 99 chicks" 2)
       ==> "99 eggs or chicks (99)"
      

    19. Unit: syntax-case

      Hieb's and Dybvig's hygienic macro package. Provides syntax-case and syntax-rules. A postscript manual can be found here: Indiana University Computer Science Department, Technical Report #356

      Notes:

      • To use the macro-system in compiled or interpreted code, just give the -hygienic option to the compiler or interpreter. The unit has only to be declared as used, if compiled code invokes macroexpand or eval with high-level macro syntax forms.
      • The macros define-macro, define-id-macro, let-macro, let-id-macro, let-optionals, define-entry-point and the procedure undefine-macro! can not be used.
      • define-values is not allowed in internal definitions.
      • Line-number information of expanded macro-forms is not fully recovered.
      • The match package uses low-level macros and does not work in combination with this macro system.
      • define-syntax can not be used inside an eval-when form.

    20. Unit: srfi-18

      A simple multithreading package. This threading package follows largely the specification of SRFI-18. For more information see documentation for SRFI-18.

      Notes:

      • Blocking I/O will block all threads.
      • It is generally not a good idea for one thread to call a continuation created by another thread, if dynamic-wind is involved.
      • When more than one thread compete for the current time-slice, the thread that was waiting first will become the next runnable thread.
      • The dynamic environment of a thread consists of the following state:
        • The current input-, output- and error-port
        • The current exception handler
        • The values of all current parameters (created by make-parameter)
        • Any pending dynamic-wind thunks.
      [procedure] (thread-quantum THREAD)
      Returns the quantum of THREAD, which is an exact integer specifying the approximate time-slice of the thread.
      [procedure] (thread-quantum-set! THREAD QUANTUM)
      Sets the quantum of THREAD to QUANTUM.

    21. Unit: format

      (This library unit is autoloaded into the interpreter csi on the first invocation of format).

      [procedure] (format DESTINATION FORMAT-STRING . ARGUMENTS)

      An almost complete implementation of Common LISP format description according to the CL reference book Common LISP from Guy L. Steele, Digital Press. This code was originally part of SLIB. The author is Dirk Lutzebaeck.

      Returns #t, #f or a string; has side effect of printing according to FORMAT-STRING. If DESTINATION is #t, the output is to the current output port and #t is returned. If DESTINATION is #f, a formatted string is returned as the result of the call. If DESTINATION is a string, DESTINATION is regarded as the format string; FORMAT-STRING is then the first argument and the output is returned as a string. If DESTINATION is a number, the output is to the value of (current-error-port). Otherwise DESTINATION must be an output port and #t is returned.

      FORMAT-STRING must be a string. In case of a formatting error format returns #f and prints a message on the value of (current-error-port). Characters are output as if the string were output by the display function with the exception of those prefixed by a tilde (~). For a detailed description of the FORMAT-STRING syntax please consult a Common LISP format reference manual. A list of all supported, non-supported and extended directives can be found in format.txt.

      This unit uses definitions from the extras unit.

    22. Unit: unistd

      This unit provides services as used on many UNIX-like systems. This unit uses the regex unit. Note that the following definitions are not availabe on non-UNIX systems like Windows or DOS.

      this unit uses the regex unit.

      1. Pathname operations
        [procedure] (create-temporary-file [EXTENSION])
        Creates an empty temporary file and returns it's pathname. If EXTENSION is not given, then .tmp is used. If the environment variable TMPDIR, TEMP or TMP is set, then the pathname names a file in that directory.
        [procedure] (absolute-pathname? PATHNAME)
        Returns #t if the string PATHNAME names an absolute pathname, and returns #f otherwise.
        [procedure] (decompose-pathname PATHNAME)
        Returns three values: the directory-, filename- and extension-components of the file named by the string PATHNAME. For any component that is not contained in PATHNAME, #f is returned.
        [procedure] (make-pathname DIRECTORY FILENAME [EXTENSION])
        [procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION]
        Returns a string that names the file with the components DIRECTORY, FILENAME and (optionally) EXTENSION. DIRECTORY can be #f (meaning no directory component), a string or a list of strings. FILENAME and EXTENSION should be strings or #f.
        make-absolute-pathname returns always an absolute pathname.
        [procedure] (pathname-directory PATHNAME>
        [procedure] (pathname-file PATHNAME)
        [procedure] (pathname-extension PATHNAME)
        Accessors for the components of PATHNAME. If the pathname does not contain the accessed component, then #f is returned.
        [procedure] (pathname-replace-directory PATHNAME DIRECTORY)
        [procedure] (pathname-replace-file PATHNAME FILENAME)
        [procedure] (pathname-replace-extension PATHNAME EXTENSION)
        Return a new pathname with the specified component of PATHANME replaced by a new value.
        [procedure] (pathname-strip-directory PATHNAME)
        [procedure] (pathname-strip-extension PATHNAME)
        Return a new pathname with the specified component of PATHNAME stripped.

      2. Directories
        [procedure] (change-directory NAME)
        Changes the current working directory to NAME.
        [procedure] (current-directory)
        Returns the name of the current working directory.
        [procedure] (create-directory NAME)
        Creates a directory with the pathname NAME.
        [procedure] (delete-directory NAME)
        Deletes the directory with the pathname NAME. The directory has to be empty.
        [procedure] (directory PATHNAME)
        Returns a list with all files that are contained in the directory with the name PATHNAME.
        [procedure] (directory? NAME)
        Returns #t if there exists a file with the name NAME and if that file is a directory, or #f otherwise.
        [procedure] (glob PATTERN1 ...)
        Returns a list of the pathnames of all existing files matching PATTERN1 ..., which should be strings containing the usual file-patterns (with * matching zero or more characters and ? matching zero or one character).

      3. Pipes
        [procedure] (call-with-input-pipe CMDLINE PROC [MODE])
        [procedure] (call-with-output-pipe CMDLINE PROC [MODE])
        Call PROC with a single argument: a input- or output port for a pipe connected to the subprocess named in CMDLINE. If PROC returns normally, the pipe is closed and any result values are returned.
        [procedure] (close-input-pipe PORT)
        [procedure] (close-output-pipe PORT)
        Closes the pipe given in PORT and waits until the connected subprocess finishes.
        [procedure] (create-pipe)
        The fundamental pipe-creation operator. Calls the C function pipe() and returns 2 values: the file-descriptors of the input- and output-ends of the pipe.
        [procedure] (open-input-pipe CMDLINE [MODE])
        Spawns a subprocess with the command-line string CMDLINE and returns a port, from which the output of the process can be read. If MODE is specified, it should be the keyword #:text (the default) or #:binary.
        [procedure] (open-output-pipe CMDLINE [MODE])
        Spawns a subprocess with the command-line string CMDLINE and returns a port. Anything written to that port is treated as the input for the process. If MODE is specified, it should be the keyword #:text (the default) or #:binary.
        [limit] pipe/buf
        This variable contains the maximal number of bytes that can be written atomically into a pipe or FIFO.
        [procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
        [procedure] (with-output-to-pipe CMDLINE THUNK [MODE])
        Temprorarily set the value of current-input-port/current-output-port to a port for a pipe connected to the subprocess named in CMDLINE and call the procedure THUNK with no arguments. After THUNK returns normally the pipe is closed and the standard input-/output port is restored to its previous value and any result values are returned.
        (with-output-to-pipe 
            "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
          (lambda ()
            (print #<<EOF
        %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
        /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
        H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
        X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
        F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
        Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
        ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
        V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g{[}{]}J}J
        cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
        EOF
        ) ) )
        

      4. Fifos
        [procedure] (create-fifo FILENAME [MODE])
        Creates a FIFO with the name FILENAME and the permission bits MODE, which defaults to
        (+ perm/irwxu perm/irwxg perm/irwxo)
        [procedure] (fifo? FILENAME)
        Returns #t if the file with the name FILENAME names a FIFO.

      5. File descriptors and low-level I/O
        [procedure] (duplicate-fileno OLD [NEW])
        If NEW is given, then the file-descriptor NEW is opened to access the file with the file-descriptor OLD. Otherwise a fresh file-descriptor accessing the same file as OLD is returned.
        [procedure] (file-close FILENO)
        Closes the input/output file with the file-descriptor FILENO.
        [procedure] (file-open FILENAME FLAGS [MODE])
        Opens the file specified with the string FILENAME and open-flags FLAGS using the C function open(). On success a file-descriptor for the opened file is returned. FLAGS should be a bitmask containing one or more of the open/... values ored together using bitwise-ior (or simply added together). The optional MODE should be a bitmask composed of one or more permission values like perm/irusr and is only relevant when a new file is created. The default mode is perm/irwxu | perm/irgrp | perm/iroth.
        [procedure] (file-read FILENO SIZE [BUFFER])
        Reads SIZE bytes from the file with the file-descriptor FILENO. If a string or bytevector is passed in the optional argument BUFFER, then this string will be destructively modified to contain the read data. This procedure returns two values: the buffer containing the data and the number of bytes read.
        [procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])
        Waits until any of the file-descriptors given in the lists READFDLIST and WRITEFDLIST is ready for input or output, respectively. If the optional argument TIMEOUT is given and not false, then it should specify the number of seconds after which the wait is to be aborted. This procedure returns two values: the lists of file-descriptors ready for input and output, respectively.
        [procedure] (file-write FILENO BUFFER [SIZE])
        Writes the contents of the string or bytevector BUFFER into the file with the file-descriptor FILENO. If the optional argument SIZE is given, then only the specified number of bytes are written.
        [file descriptor] fileno/stdin
        [file descriptor] fileno/stdout
        [file descriptor] fileno/stderr
        These variables contain file-descriptors for the standard I/O files.
        [flag] open/rdonly
        [flag] open/wronly 
        [flag] open/rdwr 
        [flag] open/read 
        [flag] open/write 
        [flag] open/creat 
        [flag] open/append 
        [flag] open/excl 
        [flag] open/noctty 
        [flag] open/nonblock 
        [flag] open/trunc 
        [flag] open/sync
        Flags for use with file-open.
        [procedure] (open-input-file* FILENO [OPENMODE])
        [procedure] (open-output-file* FILENO [OPENMODE])
        Opens file for the file-descriptor FILENO for input or output and returns a port. FILENO should be a positive exact integer. OPENMODE specifies an additional mode for opening the file (currently only the keyword #:append is supported, which opens an output-file for appending).
        [procedure] (port->fileno PORT)
        If PORT is a file-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

      6. Retrieving file attributes
        [procedure] (file-modification-time FILENAME)
        Returns time of last modification of the file with the name FILENAME. If the file does not exist, an error is signaled.
        [procedure] (file-position FILE)
        Returns the current file position of FILE, which should be a port or a file-descriptor.
        [procedure] (file-size FILENAME)
        Returns the size of the file designated by the pathname FILENAME. If the file does not exist, an error is signaled.
        [procedure] (set-file-position! FILE POSITION [WHENCE])
        Sets the current read/write position of FILE to POSITION, which should be an exact integer. FILE should be a port or a file-descriptor. WHENCE specifies how the position is to interpreted and should be one of the values seek/set, seek/cur and seek/end. It defaults to seek/set.

      7. Processes
        [procedure] (current-process-id)
        Returns the process ID of the current process.
        [procedure] (parent-process-id)
        Returns the process ID of the parent of the current process.
        [procedure] (process-execute PATHNAME [LIST])
        Creates a new child process and replaces the running process with it using the UNIX system call execv(). If the optional argument LIST is given, then it should contain a list of strings which are passed as arguments to the subprocess.
        [procedure] (process-fork [THUNK])
        Creates a new child process with the UNIX system call fork(). Returns either the PID of the child process or 0. If THUNK is given, then the child process calls it as a procedure with no arguments and terminates.
        [procedure] (process-run PATHNAME [LIST])
        Creates a new child process using the UNIX system call fork() that executes the program given by the string PATHNAME using the UNIX system call execv(). The PID of the new process is returned. If LIST is not specified, then FILENAME is passed to a program named by the environment variable SHELL (or /bin/sh, if the variable is not defined), so usual argument expansion can take place.
        [procedure] (process-signal PID [SIGNAL])
        Sends SIGNAL to the process with the id PID using the UNIX system call kill(). SIGNAL defaults to the value of the variable signal/term.
        [procedure] (process-wait [PID [NOHANG]])
        Suspends the current process until the child process with the id PID has terminated using the UNIX system call waitpid(). If PID is not given, then this procedure waits for any child process. If NOHANG is given and not #f then the current process is not suspended. This procedure returns three values:

        1. PID or 0, if NOHANG is true and the child process has not terminated yet;
        2. #t if the process exited normally or #f otherwise;
        3. either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.

      8. Symbolic links
        [procedure] (create-symbolic-link OLDNAME NEWNAME)
        Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.
        [procedure] (read-symbolic-link FILENAME)
        Returns the filename to which the symbolic link FILENAME points.

      9. Permissions, owners, users and groups
        [procedure] (file-owner FILENAME)
        Returns the user-id of the file named FILENAME.
        [procedure] (file-permissions FILENAME)
        Returns the permission bits for the file named FILENAME. You can test this value by performing bitwise operations on the result and the perm/... values.
        [procedure] (file-read-access? FILENAME [REALUID])
        [procedure] (file-write-access? FILENAME [REALUID])
        [procedure] (file-execute-access? FILENAME [REALUID])
        These procedures return #t if the owner of the file has read, write or execute permissions on the file named FILENAME. If the optional parameter REALUID is given and not false, then the real user id of the process is used for the test. Otherwise the effective user id is taken.
        [procedure] (change-file-mode FILENAME MODE)
        Changes the current file mode of the file named FILENAME to MODE using the chmod() system call. The perm/... variables contain the various permission bits and can be combinded with the bitwise-ior procedure.
        [procedure] (change-file-owner FILENAME UID GID)
        Changes the owner information of the file named FILENAME to the user- and group-ids UID and GID (which should be exact integers) using the chown() system call.
        [procedure] (current-user-id)
        [procedure] (current-group-id)
        [procedure] (current-effective-user-id)
        [procedure] (current-effective-group-id)
        Return the user- and group-ids of the current process.
        [permission bits] perm/irusr
        [permission bits] perm/iwusr
        [permission bits] perm/ixusr
        [permission bits] perm/irgrp
        [permission bits] perm/iwgrp
        [permission bits] perm/ixgrp
        [permission bits] perm/iroth
        [permission bits] perm/iwoth
        [permission bits] perm/ixoth
        [permission bits] perm/irwxu
        [permission bits] perm/irwxg
        [permission bits] perm/irwxo
        [permission bits] perm/isvtx
        [permission bits] perm/isuid
        [permission bits] perm/isgid
        These variables contain permission bits as used in change-file-mode.
        [procedure] (set-user-id! UID)
        Sets the effective user id of the current process to UID, which should be a positive integer.

      10. Record locking
        [procedure] (file-lock PORT [START [LEN]])
        Locks the file associated with PORT for reading or writing (according to wether PORT is an input- or output-port). START specifies the starting position in the file to be locked and defaults to 0. LEN specifies the length of the portion to be locked and defaults to #t, which means the complete file. file-lock returns a "lock"-object.
        [procedure] (file-test-lock PORT [START [LEN]])
        Tests wether the file associated with PORT is locked for reading or writing (according to wether PORT is an input- or output-port) and returns either #f or the process-id of the locking process.
        [procedure] (file-unlock LOCK)
        Unlocks the previously locked portion of a file given in LOCK.

      11. Signal handling
        [procedure] (set-alarm! SECONDS)
        Sets an internal timer to raise the signal/alrm after SECONDS are elapsed. You can use the set-signal-handler! procedure to write a handler for this signal.
        [procedure] (set-signal-handler! SIGNUM PROC [DISABLED])
        Establishes the procedure of one argument PROC as the handler for the signal with the code SIGNAL. PROC is called with the signal number as its sole argument. If the optional argument DISABLED is given and not #f then interrupts are disabled trough the execution of the signal handler. The default is to enable interrupts. If the argument PROC is #f then this signal will be ignored.
        [procedure] (set-signal-mask! SIGLIST)
        Sets the signal mask of the current process to block all signals given in the list SIGLIST. Signals masked in that way will not be delivered to the current process.
        [signal code] signal/term
        [signal code] signal/kill
        [signal code] signal/int
        [signal code] signal/hup
        [signal code] signal/fpe
        [signal code] signal/ill
        [signal code] signal/segv
        [signal code] signal/abrt
        [signal code] signal/trap
        [signal code] signal/quit
        [signal code] signal/alrm
        [signal code] signal/vtalrm
        [signal code] signal/prof
        [signal code] signal/io
        [signal code] signal/urg
        [signal code] signal/chld
        [signal code] signal/cont
        [signal code] signal/stop
        [signal code] signal/tstp
        [signal code] signal/pipe
        [signal code] signal/xcpu
        [signal code] signal/xfsz
        [signal code] signal/usr1
        [signal code] signal/usr2
        [signal code] signal/winch
        These variables contain signal codes for use with process-signal or set-signal-handler!.

      12. Environment access
        [procedure] (current-environment)
        Returns a association list of the environment variables and their current values.
        [procedure] (setenv VARIABLE VALUE)
        Sets the environment variable named VARIABLE to VALUE. Both arguments should be strings. If the variable is not defined in the environment, a new definition is created.
        [procedure] (unsetenv VARIABLE)
        Removes the definition of the environment variable VARIABLE from the environment of the current process. If the variable os not defined, nothing happens.

      13. Memory mapped I/O
        [procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
        Maps a section of a file to memory using the C function mmap(). ADDRESS should be a foreign pointer object or #f; LEN specifies the size of the section to be mapped; PROTECTION should be one or more of the flags prot/read, prot/write, prot/exec or prot/none bitwise-iored together; FLAG should be one or more of the flags map/fixed, map/shared, map/private, map/anonymous or map/file; FILENO should be the file-descriptor of the mapped file. The optional argument OFFSET gives the offset of the section of the file to be mapped and defaults to 0. This procedure returns an object representing the mapped file section.
        The procedure move-memory! can be used to access the mapped memory.
        [procedure] (unmap-file-from-memory MMAP [LEN])
        Unmaps the section of a file mapped to memory using the C function munmap(). MMAP should be a mapped file as returned by the procedure map-file-to-memory. The optional argument LEN specifies the length of the section to be unmapped and defaults to the complete length given when the file was mapped.

      14. Time routines
        [procedure] (seconds->local-time SECONDS)
        Breaks down the time value represented in SECONDS into a 10 element vector of the form #(second minute hours mday month year wday yday dstflag timezone). You can obtain the number of seconds using the library procedure current-seconds. The last item in the result vector timezone contains the difference between UTC and local time in seconds west of UTC (using the C variable timezone).
        [procedure] (seconds->string SECONDS)
        Converts the local time represented in SECONDS into a string of the form "Tue May 21 13:46:22 1991\n".
        [procedure] (seconds->utc-time SECONDS)
        Similar to seconds->local-time, but interpretes SECONDS as local time.
        [procedure] (time->string VECTOR)
        Converts the broken down time represented in the 8 element vector VECTOR into a string of the form "Tue May 21 13:46:22 1991\n".

      15. Miscellanous routines
        [procedure] (_exit [CODE])
        Exits the current process without flushing any buffered output (using the C function _exit). Note that the exit-handler is not called when this procedure is invoked. The optional return-code CODE defaults to 0.
        [error code] errno/perm
        [error code] errno/noent
        [error code] errno/srch
        [error code] errno/intr
        [error code] errno/io
        [error code] errno/noexec
        [error code] errno/badf
        [error code] errno/child
        [error code] errno/nomem
        [error code] errno/acces
        [error code] errno/fault
        [error code] errno/busy
        [error code] errno/notdir
        [error code] errno/isdir
        [error code] errno/inval
        [error code] errno/mfile
        [error code] errno/nospc
        [error code] errno/spipe
        [error code] errno/pipe
        [error code] errno/again
        [error code] errno/rofs
        These variables contain error codes as returned by errno.
        [procedure] (file-truncate FILE OFFSET)
        Truncates the file FILE to the length OFFSET, which should be an integer. If the file-size is smaller or equal to OFFSET then nothing is done. FILE should be a filename or a file-descriptor.
        [procedure] (get-host-name)
        Returns the hostname of the machine that this process is running on.
        [procedure] (set-buffering-mode! PORT MODE [BUFSIZE])
        Sets the buffering-mode for the file associated with PORT to MODE, which should be one of the keywords #:full, #:line or #:none. If BUFSIZE is specified it determines the size of the buffer to be used (if any).
        [procedure] (terminal-name PORT)
        Returns the name of the terminal that is connected to PORT.
        [procedure] (terminal-port? PORT)
        Returns #t if PORT is connected to a terminal and #f otherwise.
        [procedure] (system-information)
        Invokes the UNIX system call uname() and returns 5 values: system-name, node-name, OS release, OS version and machine.
        [procedure] (user-information USER)
        If USER specifes a valid username (as a string) or user ID, then the user database is consulted and 7 values are returned: the user-name, the encrypted password, the user ID, the group ID, a user-specific string, the home directory and the default shell. If no user with this name or ID can be found, then #f is returned.

      16. How Scheme procedures relate to UNIX C functions
        change-directory chdir
        change-file-mode chmod
        change-file-owner chown
        create-directory mkdir
        create-fifo mkfifo
        create-pipe pipe
        create-symbolic-link link
        current-directory curdir
        current-effective-groupd-id getegid
        current-effective-user-id geteuid
        current-group-id getgid
        current-parent-id getppid
        current-process-id getpid
        current-user-id getuid
        delete-directory rmdir
        duplicate-fileno dup/dup2
        _exit _exit
        file-close close
        file-execute-access? access
        file-open open
        file-lock fcntl
        file-position ftell/lseek
        file-read read
        file-read-access? access
        file-select select
        file-test-lock fcntl
        file-truncate truncate/ftruncate
        file-unlock fcntl
        file-write write
        file-write-access? access
        get-host-name gethostname
        map-file-to-memory mmap
        open-input-file* fdopen
        open-output-file* fdopen
        open-input-pipe popen
        open-output-pipe popen
        port->fileno fileno
        process-execute execvp
        process-fork fork
        process-signal kill
        process-wait waitpid
        close-input-pipe pclose
        close-output-pipe pclose
        read-symbolic-link readlink
        seconds->local-time localtime
        seconds->string ctime
        seconds->utc-time gmtime
        set-alarm! alarm
        set-buffering-mode! setvbuf
        set-file-position! fseek/seek
        set-signal-mask! sigprocmask
        set-user-id! setuid
        setenv setenv/putenv
        system-information uname
        terminal-name ttyname
        terminal-port? isatty
        time->string asctime
        unsetenv putenv
        unmap-file-from-memory munmap
        user-information getpwnam/getpwuid

    23. Unit: lolevel

      This unit provides a number of handy low-level operations. Use at your own risk.

      This unit uses the srfi-4 and extras units.

      1. Foreign pointers
        [procedure] (address->pointer ADDRESS)
        Creates a new foreign pointer object initialized to point to the address given in the integer ADDRESS.
        [procedure] (null-pointer)
        Another way to say (address->pointer 0).
        [procedure] (null-pointer? PTR)
        Returns #t if PTR contains a NULL pointer, or #f otherwise.
        [procedure] (pointer? X)
        Returns #t if X is a foreign pointer object, and #f otherwise.
        [procedure] (pointer->address PTR)
        Returns the address, to which the pointer PTR points.

      2. Serialization
        [procedure] (deserialize U32VECTOR [SAFE])
        Transforms serialized data in U32VECTOR back into a Scheme object. If the optional argument SAFE is given and not #f, then any attempt to deserialize a process specific object like a closure, port or foreign pointer will signal an error.
        [procedure] (serialize OBJECT)
        Transforms the Scheme object OBJECT into an u32vector and returns that vector.

      3. Extending procedures with data
        [procedure] (extend-procedure PROCEDURE X)
        Returns a copy of the procedure PROCEDURE which contains an additional data slot initialized to X.
        [procedure] (extended-procedure? PROCEDURE)
        Returns #t if PROCEDURE is an extended procedure, or #f otherwise.
        [procedure] (procedure-data PROCEDURE)
        Returns the data object contained in the extended procedure PROCEDURE.
        [procedure] (set-procedure-data! PROCEDURE X)
        Changes the data object contained in the extended procedure PROCEDURE to X.
        (define foo
          (letrec ((f (lambda () (procedure-data x)))
                   (x #f) )
            (set! x (extend-procedure f 123))
            x) )
        (foo)                                         ==> 123
        (set-procedure-data! foo 'hello)
        (foo)                                         ==> hello
        

      4. Bytevectors
        [procedure] (byte-vector FIXNUM ...)
        Returns a freshly allocated byte-vector with FIXNUM ... as its initial contents.
        [procedure] (byte-vector? X)
        Returns #t if X is a byte-vector object, or #f otherwise.
        [procedure] (byte-vector-fill! BYTE-VECTOR N)
        Sets each element of BYTE-VECTOR to N, which should be an exact integer.
        [procedure] (byte-vector->list BYTE-VECTOR)
        Returns a list with elements taken from BYTE-VECTOR.
        [procedure] (byte-vector-length BYTE-VECTOR)
        Returns the number of elements in BYTE-VECTOR.
        [procedure] (byte-vector-ref BYTE-VECTOR INDEX)
        Returns the byte at the INDEXth position of BYTE-VECTOR.
        [procedure] (byte-vector-set! BYTE-VECTOR INDEX N)
        Sets the byte at the INDEXth position of BYTE-VECTOR to the value of the exact integer n.
        [procedure] (executable-byte-vector->procedure PBYTE-VECTOR)
        Returns a procedure that on invocation will execute the code in PBYTE-VECTOR, which should have been allocated using make-executable-byte-vector.
        The procedure follows the native C calling convention, and will be called as if declared with the following prototype:
        void <procedure>(int argc, C_word closure, C_word k, C_word arg1, ...)
        • argc contains the number of arguments arg1, ... that are passed plus 2 (including closure and k).
        • closure is the procedure object itself.
        • k is a continuation closure that should be called when the code is about to return.
          typedef void (*CONTINUATION)(int argc, C_word closure, C_word result);
          
          ((CONTINUATION)k[ 1 ])(2, k, result)
          (k is a data object with the second word being the actual code pointer)

        An example:

        (define x (make-executable-byte-vector 17))
        (move-memory! 
         '#u8(#x8b #x44 #x24 #x0c		; movl 12(%esp), %eax     - `k'
              #x8b #x5c #x24 #x10               ; movl 16(%esp), %ebx     - `arg1'
              #x53				; pushl %ebx              - push result
              #x50				; pushl %eax              - push k
              #x6a #x02                         ; pushl $2                - push argument count
              #x8b #x40 #x04			; movl 4(%eax), %eax      - fetch code pointer
              #xff #xd0)			; call *%eax
         x)
        (define y (executable-byte-vector->procedure x))
        (y 123)                                         ==> 123
        

        The result of calling executable-byte-vector->procedure with a non-executable statically allocated byte-vector is undefined.

        [procedure] (list->byte-vector LIST)
        Returns a byte-vector with elements taken from LIST, where the elements of LIST should be exact integers.
        [procedure] (make-byte-vector SIZE [INIT])
        Creates a new byte-vector of size SIZE. If INIT is given, then it should be an exact integer with which every element of the byte-vector is initialized.
        [procedure] (make-executable-byte-vector SIZE [INIT])
        As make-static-byte-vector, but the code is suitable for execution.
        Note: this feature is currently only available on x86 platforms.
        [procedure] (make-static-byte-vector SIZE [INIT])
        As make-byte-vector, but allocates the byte-vector in storage that is not subject to garbage collection. To free the allocated memory, one has to call release explicitly.
        [procedure] (static-byte-vector->pointer PBYTE-VECTOR)
        Returns a pointer object pointing to the data in the statically allocated byte-vector PBYTE-VECTOR.

      5. Miscellanous routines
        [procedure] (block-ref BLOCK INDEX)
        Returns the contents of the INDEXth slot of the object BLOCK. BLOCK may be a vector, record structure, pair or symbol.
        [procedure] (block-set! BLOCK INDEX X)
        Sets the contents of the INDEXth slot of the object BLOCK to the value of X. BLOCK may be a vector, record structure, pair or symbol.
        [procedure] (copy X)
        Copies X recursively and returns the fresh copy. Objects allocated in static memory are copied back into garbage collected storage.
        [procedure] (evict X [ALLOCATOR])
        Copies the object X recursively into the memory pointed to by the foreign pointer object returned by ALLOCATOR, which should be a procedure of a single argument (the number of bytes to allocate). The freshly copied object is returned.
        This facility allows moving arbitrary objects into static memory, but care should be taken when mutating evicted data: setting slots in evicted vector-like objects to non-evicted data is not allowed. It is possible to set characters/bytes in evicted strings or byte-vectors, though. It is advisable not to evict ports, because they might be mutated by certain file-operations.
        Objects allocated in static memory are not copied.
        evict is able to handle circular and shared structures, but evicted symbols are no longer unique: a fresh copy of the symbol is created, so
        (define x 'foo)
        (define y (evict 'foo))
        y                              ==> foo
        (eq? x y)                      ==> #f
        (define z (evict '(bar bar)))
        (eq? (car z) (cadr z))         ==> #t
        

        The ALLOCATOR defaults to the C-library malloc().
        [procedure] (evicted? X)
        Returns #t if X is a non-immediate evicted data object, or #f otherwise.
        [procedure] (move-memory! FROM TO [BYTES])
        Copies BYTES bytes of memory from FROM to TO. FROM and TO may be strings, primitive byte-vectors, SRFI-4 byte-vectors (see: srfi-4 unit), memory mapped files or foreign pointers (as obtained from a call to foreign-lambda, for example). if BYTES is not given and the size of the source or destination operand is known then the maximal number of bytes will be copied.
        [procedure] (number-of-slots BLOCK)
        Returns the number of slots that the object BLOCK contains. BLOCK may be a vector, record structure, pair or symbol.
        [procedure] (release X [RELEASER])
        Frees memory occupied by the evicted object X recursively. RELEASER should be a procedure of a single argument (a foreign pointer object to the static memory to be freed) and defaults to the C-library free().

    24. Unit: tinyclos

      This unit is a port of Gregor Kiczales TinyCLOS with numerous modifications.

      This unit uses the extras unit.

      1. Defining forms
        [syntax] (define-class NAME (SUPERCLASS1 ...) (SLOTNAME1 ...) [METACLASS])
        Sets the variable NAME to a new class (a new instance of the class <class>). SUPERCLASS1 ... is a list of superclasses of the newly created class. If no superclasses are given, then <object> is assumed. SLOTNAME1 ... are the names of the direct slots of the class. if METACLASS is provided, then the new class-instance is an instance of METACLASS instead of <class>.
        (define-class NAME (SUPER) (SLOT1 SLOT2) META)
        is equivalent to
        (define NAME
          (make META 
            'name 'NAME
            'direct-supers (list SUPER)
            'direct-slots (list 'SLOT1 'SLOT2)) )
        Note that slots-names are not required to by symbols, so the following is perfectly valid:
        (define hidden-slot (list 'hidden))
        (define <myclass>
          (make <class>
             'direct-supers (list <object>)
             'direct-slots (list hidden-slot) ) )
        (define x1 (make <myclass>)
        (slot-set! x1 hidden-slot 99)
        [syntax] (define-generic NAME)
        Sets the variable NAME to contain a fresh generic function object without associated methods.
        [syntax] (define-method (NAME (VARIABLE1 CLASS1) ... PARAMETERS ...) BODY ...)
        Adds a new method with the code BODY ... to the generic function that was assigned to the variable name. CLASS1 ... is a list if classes that specialize this particular method. The method can have additional parameters PARAMETERS, which do not specialize the method any further.
        Inside the body of the method the identifier call-next-method names a procedure of zero arguments that can be invoked to call the next applicable method with the same arguments.
        If no generic function is defined under this name, then it a fresh generic function object is created and assigned to NAME.

      2. Base language
        [procedure] (add-method GENERIC METHOD)
        Adds the method object METHOD to the list of applicable methods for the generic function GENERIC.
        [procedure] (instance? X)
        Returns #t if X is an instance of a non-primitive class.
        [procedure] (make CLASS INITARG ...)
        Creates a new instance of CLASS and passes INITARG ... to the initialize method of this class.
        [procedure] (make-class SUPERCLASSES SLOTNAMES)
        Creates a new class object, where SUPERCLASSES should be the list of direct superclass objects and SLOTNAMES should be a list of symbols naming the slots of this class.
        [procedure] (make-generic [NAME])
        Creates a new generic function object. If NAME is specified, then it should be a string.
        [procedure] (make-method SPECIALIZERS PROC)
        Creates a new method object specialized to the list of classes in SPECIALIZERS.
        (define-method (foo (<bar> x)) 123)
           <=> (add-method foo (make-method (list <bar>) (lambda (call-next-method x) 123)))
        
        [procedure] (slot-ref INSTANCE SLOTNAME)
        Returns the value of the slot SLOTNAME of the object INSTANCE.
        [procedure] (slot-set! INSTANCE SLOTNAME VALUE)
        Sets the value of the slot SLOTNAME of the object INSTANCE to VALUE.

      3. Introspectiion
        [procedure] (class-cpl CLASS)
        Returns the class-precedence-list of CLASS as a list of classes.
        [procedure] (class-direct-slots CLASS)
        Returns the list of direct slots of CLASS as a list of lists, where each sublist contains the name of the slot.
        [procedure] (class-direct-supers CLASS)
        Returns the list of direct superclasses of CLASS.
        [procedure] (class-of X)
        Returns the class that the object X is an instance of.
        [procedure] (class-name CLASS)
        Returns name of CLASS.
        [procedure] (class-slots CLASS)
        Returns the list of all slots of CLASS and it's superclasses as a list of lists, where each sublist contains the name of the slot.
        [procedure] (generic-methods GENERIC)
        Returns the list of all methods associated with the generic function GENERIC.
        [procedure] (method-specializers METHOD)
        Returns the list of classes that specialize METHOD.
        [procedure] (method-procedure METHOD)
        Returns the procedure that contains the body of METHOD.
        [procedure] (subclass? CLASS1 CLASS2)
        Returns #t is CLASS1 is a subclass of CLASS2, or #f otherwise. Note that the following holds:
        (subclass? X X) ==> #t

      4. Intercessory protocol
        [generic] (allocate-instance CLASS)
        Allocates storage for an instance of CLASS and returns the instance.
        [generic] (compute-apply-generic GENERIC)
        [generic] (compute-apply-methods GENERIC)
        [generic] (compute-methods GENERIC)
        These are used to compute the actual methods to be called on the invocation of the generic function GENERIC.
        [generic] (compute-cpl CLASS)
        Computes and returns the class-precedence-list of CLASS.
        [generic] (compute-getter-and-setter CLASS SLOT ALLOCATOR)
        Returns two values, the procedures that get and set the contents of the slot SLOT. ALLOCATOR is a procedure of one argument (I currently don't know what it does).
        [generic] (compute-method-more-specific? GENERIC)
        Returns a procedure of three arguments (two methods and a list of arguments) that returns #t if the first method is more specific than the second one with respect to the list of arguments. Otherwise the returned predicate returns #f.
        [generic] (compute-slots CLASS)
        Computes and returns the list of slots of CLASS.
        [generic] (initialize INSTANCE INITARGS)
        Initializes the object INSTANCE. INITARGS is the list of initialization arguments that were passed to the make procedure.

      5. Additional protocol
        [generic] (describe-object INSTANCE PORT)
        Writes a description of INSTANCE to PORT. Execution of the interpreter command ,d or calling describe will invoke this generic function.
        [generic] (print-object INSTANCE PORT)
        Writes a textual representation of INSTANCE to PORT. Any output of an instance with display, write and print will invoke this generic function.

      6. Utility procedures
        [procedure] (initialize-slots INSTANCE INITARGS)
        This procedure takes a sequence of alternating slot-names and initialization values in INITARGS and initializes the corresponding slots in INSTANCE.
        (define-class <pos> () (x y))
        
        (define-method (initialize (<pos> pos) initargs)
          (call-next-method)
          (initialize-slots pos initargs))
        
        (define p1 (make <pos> 'x 1 'y 2))
        (define p2 (make <pos> 'x 3 'y 5))
        

      7. Builtin classes

        The class hierarchy of builtin classes looks like this:

        
        <top>
          <object>
            <class>
              <procedure-class>
                <procedure>
                <entity-class>
                  <generic>
              <primitive-class>
          <primitive>
            <void>
            <boolean>
            <symbol>
            <char>
            <vector>
            <pair>
            <number>
              <exact>
              <inexact>
            <string>
            <port>
              <input-port>
              <output-port>
            <byte-vector>
              <u8vector>
              <s8vector>
              <u16vector>
              <s16vector>
              <u32vector>
              <s32vector>
              <f32vector>
              <f64vector>
            <structure>
              <environment>
              <hash-table>
              <queue>
              <time>
              <lock>
              <mmap>
              <condition>
            <end-of-file>
        [class] <primitive>           --> <top>
        The parent class of the classes of all primitive Scheme objects.
        [class] <boolean>             --> <primitive>
        [class] <symbol>              --> <primitive>
        [class] <char>                --> <primitive>
        [class] <vector>              --> <primitive>
        [class] <null>                --> <primitive>
        [class] <pair>                --> <primitive>
        [class] <number>              --> <primitive>
        [class] <exact>               --> <number>
        [class] <inexact>             --> <number>
        [class] <string>              --> <primitive>
        [class] <port>                --> <primitive>
        [class] <byte-vector>          --> <primitive>
        [class] <structure>           --> <primitive>
        [class] <environment>         --> <structure>
        [class] <hash-table>          --> <structure>
        [class] <queue>               --> <structure>
        [class] <end-of-file>         --> <primitive>
        [class] <input-port>          --> <port>
        [class] <output-port>         --> <port>
        [class] <procedure>           --> <procedure-class>
        The classes of primitive Scheme objects.
        [class] <class>               --> <object>
        The parent class of all class objects.
        [class] <entity-class>        --> <class>
        The parent class of objects that can be invoked as a procedure and have slots.
        [class] <generic>             --> <entity-class>
        The parent class of generic function objects.
        [class] <method>              --> <class>
        The parent class of method objects.
        [class] <object>              --> <class>
        The parent class of all objects.
        [class] <procedure-class>     --> <class>
        The parent class of objects that can be invoked as a procedure.
        [class] <condition>           --> <structure>
        Class of condition objects.
        [class] <time>                --> <structure>
        Class of time-objects as defined in SRFI-18.
        [class] <char-set>            --> <structure>
        Class of character-set objects as defined in SRFI-14.
        [class] <u8vector>            --> <byte-vector>
        [class] <s8vector>            --> <byte-vector>
        [class] <u16vector>           --> <byte-vector>
        [class] <s16vector>           --> <byte-vector>
        [class] <u32vector>           --> <byte-vector>
        [class] <s32vector>           --> <byte-vector>
        [class] <f32vector>           --> <byte-vector>
        [class] <f64vector>           --> <byte-vector>
        Classes for SRFI-4 byte-vector objects.
        [class] <lock>                --> <structure>
        [class] <mmap>                --> <structure>
        Classes of objects used in the unistd library unit.

    25. Additional files

      In addition to library units the following files are provided. Use them by including the file in your code with the include special form.

      1. describe.scm

        Some procedures for printing descriptions of arbitrary data objects.

        (This file is autoloaded into the interpreter csi on the first invocation of describe or dump).

        This include file defines a module named describe, which exports the symbols describe and dump.

        [procedure] (describe EXP [PORT])
        Print description of EXP to PORT or the value of (current-output-port).
        [procedure] (dump EXP [PORT])
        Writes a hex-dump of data contained in EXP to PORT or to the value of (current-output-port), if PORT is not specified. EXP may be a byte-vector or a string.

      2. process.scm

        A procedure to invoke a sub-process and communicate with it via it's standard I/O ports.
        (Only available on UNIX-like systems)

        This include file defines a module named process, which exports the symbol process.

        (This file is autoloaded into the interpreter csi on the first invocation of process).

        [procedure] (process COMMANDLINE)
        Passes the string COMMANDLINE to the host-system's shell that is invoked as a subprocess and returns three values: an input port from which data written by the sub-process can be read, an output port from which any data written to it will be received as input from the sub-process and the process-id of the started sub-process.

      3. records.scm

        Record types as defined by SRFI-9. See documentation for SRFI-9.

        This include file defines a module named srfi-9, which exports the symbol define-record-type.

      4. report.scm

        This file provides a procedure to display some status information, like heap/stack-size, features, etc.

        (This file is autoloaded into the interpreter csi on the first invocation of report).

        This include file defines a module named report, which exports the symbol report.

        [procedure] (report [PORT])
        Writes status information to PORT, or if not provided, to the value of (current-output-port).

  8. Data representation
  9. There exist two different kinds of data objects in the CHICKEN system: immediate and non-immediate objects. Immediate objects are represented by a tagged machine word, which is usually of 32 bits length (64 bits on 64-bit architectures). The immediate objects come in four different flavors:

    Non-immediate objects are blocks of data represented by a pointer into the heap. The first word of the data block contains a header, which gives information about the type of the object. The header has the size of a machine word, usually 32 bits (64 bits on 64 bit architectures).

    The actual data follows immediately after the header. Note that block-addresses are always aligned to the native machine-word boundary. Scheme data objects map to blocks in the following manner:

    Data objects may be allocated outside of the garbage collected heap, as long as their layout follows the above mentioned scheme. But care has to be taken not to mutate these objects with heap-data (i.e. non-immediate objects), because this will confuse the garbage collector.

    For more information see the header file chicken.h.


  10. Implementation notes

  11. Bugs and limitations

  12. Acknowledgements
  13. Sven Hartrumpf helped porting CHICKEN to the UltraSparc and found a number of compiler bugs.

    Kirill Lisovsky found a couple of bugs while porting Oleg Kiselyov's SSAX XML parser to CHICKEN.

    Doug Quale contributed the configuration scripts for installation on UNIX-like systems, suggested numerous improvements and was generally very helpful.

    Benedikt Rosenau found several bugs and spent a lot of time testing the system and pointing out improvements.

    Bakul Shah and Chris Moline helped porting CHICKEN to FreeBSD.

    Dennis Marti helped fixing a problem with the garbage collector under Mac OS X.

    Thanks also to Dave Bodenstab, Franklin Chen, James Crippen, Brian Denheyer, Marc Feeley, Joey Gibson, Andreas Gustafsson, Karl M. Hegbloom, William P. Heinemann, Bruce Hoult, Dale Jordan, Ron Kneusel, Charles Martin, David Rush, Oskar Schirmer, Ronald Schröder, Jeffrey B. Siegal, Jason Songhurst, Mike Thomas, Christian Tismer, Shawn Wagner, Matthew Welland and Richard Zidlicky for bug-fixes, tips and suggestions.


  14. References
  15. [1] Henry Baker: "CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A."
    [2] Revised^5 Report on the Algorithmic Language Scheme