CHICKEN - A practical and portable Scheme system. Version 2, Build 228

(declare (uses UNITNAME))

(declare (unit UNITNAME))

(include "FILENAME")

csc -help

— 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.

— parameter: user-pass-2

Holds a procedure of three arguments, which is called with the canonicalized node-graph as its sole argument. The result is ignored, so this pass has to mutate the node-structure to cause any effect.

— parameter: user-post-analysis-pass

Holds a procedure that will be called after the last performed program analysis. The procedure (when defined) will be called with three arguments: the program database, a getter and a setter-procedure which can be used to access and manipulate the program database, which holds various information about the compiled program. The getter procedure should be called with two arguments: a symbol representing the binding for which information should be retrieved, and a symbol that specifies the database-entry. The current value of the database entry will be returned or #f, if no such entry is available. The setter procedure is called with three arguments: the symbol and key and the new value.

For information about the contents of the program database contact the author.

; hello.scm

(print "Hello, world!")

% csc hello.scm -O2 -d1

# Makefile for UNIX systems

hello: hello.o runtime.o library.o eval.o extras.o
       $(CC) -o hello hello.o runtime.o library.o eval.o extras.o -lm

hello.o: chicken.h
runtime.o: chicken.h
library.o: chicken.h
eval.o: chicken.h
extras.o: chicken.h

% tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
% gzip hello.tar

  csi {FILENAME|OPTION}

— procedure: toplevel-command

          (toplevel-command SYMBOL PROC [HELPSTRING])
     

Defines or defines a toplevel interpreter command the can be invoked by entering ,SYMBOL. PROC will be invoked when the command is entered and may read any required argument via read (or read-line). If the optional argument HELPSTRING is given, it will be listed by the ,? command.

— syntax: trace

          (trace NAME ...)
     

Switches tracing on for the procedures with the given names.

— syntax: untrace

          (untrace NAME ...)
     

Switches tracing of the given procedures off.

— read syntax: #[INDEX]

          #
          #INDEX
     

Returns the result of entry number INDEX in the history list. If the expression for that entry resulted in multiple values, the first result (or an unspecified value for no values) is returned. If no INDEX is given (and if a whitespace or closing paranthesis character follows the #, then the result of the last expression is returned. Note that this facility is a reader macro and is implicitly quoted.

<formal-argument-list> ==> <required-formal-argument>*
                           [(#!optional <optional-formal-argument>*)]
                           [(#!rest <rest-formal-argument>)]
                           [(#!key <key-formal-argument>*)]
<required-formal-argument> ==> <ident>
<optional-formal-argument> ==> <ident>
                             | (<ident> <initializer>)
<rest-formal-argument> ==> <ident>
<key-formal-argument> ==> <ident>
                          | (<ident> <initializer>)
<initializer> ==> <expr>

((lambda x x) 3 4 5 6)       => (3 4 5 6)
((lambda (x y #!rest z) z)
 3 4 5 6)                    => (5 6)
((lambda (x y #!optional z #!rest r #!key i (j 1)) 
    (list x y z i: i j: j))
 3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)

     (define ((make-adder x) y) (+ x y))

     (define (make-adder x) (lambda (y) (+ x y)))

(letrec ([foo 123]
         [bar foo] )
  bar)

(let ([foo 123])
  (bar)
  (define foo 456)
  (baz foo) )

(let ([foo 123])
  (bar)
  (letrec ([foo 456])
    (baz foo) ) )

— read syntax: #| ... |#

A multiline “block” comment. May be nested. Implements SRFI-30)

— read syntax: #;EXPRESSION

Treats EXPRESSION as a comment.

— read syntax: #,(CONSTRUCTORNAME DATUM ...)

Allows user-defined extension of external representations. (For more information see the documentation for SRFI-10)

— read syntax: #'EXPRESSION

An abbreviation for (syntax EXPRESSION).

— read syntax: #$EXPRESSION

An abbreviation for (location 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 (or end of file) will be returned as a single string:

(define msg #<<END
"Hello, world!", she said. 
END
)

is equivalent to

     
     (define msg "\"Hello, world!\", she 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")

— read syntax: #> ... <#

Abbreviation for foreign-declare " ... ").

— read syntax: #>? ... <#

Abbreviation for (foreign-parse " ... ").

— read syntax: #>! ... <#

Abbreviation for (foreign-parse(declare " ... ").

— read syntax: #%...

Reads like a normal symbol.

— read syntax: #!...

Treated as a commment and ignores everything up the end of the current line. The keywords #!optional, #!rest and #!key are handled separately and returned as normal symbols. The special (self-evaluating) symbol #!eof is read as the end-of-file object. Note that if this constant appears at top-level in a loaded file, it is indistiguishable from normal end-of-file.

— read syntax: #cs...

Read the next expression in case-sensitive mode (regardless of the current global setting).

— read syntax: #ci...

Read the next expression in case-insensitive mode (regardless of the current global setting).

— read syntax: #+FEATURE EXPR

Equivalent to

          (cond-expand (FEATURE EXPR) (else))
     

— syntax: require-extension
— syntax: use

          (require-extension ID ...)
          (use ID ...)
     

This form does all necessary steps to make the libraries or extensions given in ID ... available. It loads syntactic extension, if needed and generates code for loading/linking with core library modules or separately installed extensions. use is just a shorter alias for require-extension. This implementation of require-extension is compliant to SRFI-55 (see SRFI-55 for more information).

During interpretation/evaluation require-extension performs one of the following:

• If ID names a built in features chicken srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10 srfi-9 srfi-17 srfi-55, then nothing is done.
• If ID names one of syntactic extensions chicken-match-macros chicken-more-macros chicken-ffi-macros, then this extension will be loaded.
• If ID names one of the core library units shipped with CHICKEN, then a (load-library 'ID) will be performed. If one of those libraries define specific syntax (match srfi-13), then the required source file defining the syntax will be loaded.
• If ID names an installed extension with the syntax or require-at-runtime attribute, then the equivalent of (require-for-syntax 'ID) is performed.
• Otherwise (require-extension ID) is equivalent to (require 'ID).

During compilation one of the following happens instead:

• If ID names a built in features chicken srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10 srfi-9 srfi-17 srfi-55, then nothing is done.
• If ID names one of syntactic extensions chicken-match-macros chicken-more-macros chicken-ffi-macros, then this extension will be loaded at compile-time, making the syntactic extensions available in compiled code.
• If ID names one of the core library units shipped with CHICKEN, then a (declare (uses ID)) is generated. If one of those libraries define specific syntax (match srfi-13), then the required source file defining the syntax will be loaded at compile-time, making the syntactic extension available in compiled code.
• If ID names an installed extension with the syntax or require-at-runtime attribute, then the equivalent of (require-for-syntax 'ID) is performed.
• Otherwise (require-extension ID) is equivalent to (require 'ID).

To make long matters short - just use require-extension and it will normally figure everything out for dynamically loadable extensions and core library units.

ID should be a pure extension name and should not contain any path prefixes (for example dir/lib...) is illegal).

ID may also be a list that designates an extension-specifier. Currently the following extension specifiers are defined:

• (srfi NUMBER ...) is required for SRFI-55 compatibility and is fully implemented
• (version ID NUMBER) is equivalent to ID, but checks at compile-time whether the extension named ID is installed and whether its version is equal or higher than NUMBER. NUMBER may be a string or a number, the comparison is done lexicographically (using string>=?).

See also: set-extension-specifier!

— syntax: define-extension

          (define-extension NAME CLAUSE ...)
     

This macro simplifies the task of writing extensions that can be linked both statically and dynamically. If encountered in interpreted code or code that is compiled into a shared object (specifically if compiled with the feature chicken-compile-shared, done automatically by csc when compiling with the -shared or -dynamic option) then the code given by clauses if the form

     
     (dynamic EXPRESSION ...)

is inserted into the output as a begin form.

If compiled statically (specifically if the feature chicken-compiled-shared has not been given), then this form expands into the following:

     
     (declare (unit NAME))
     (provide 'NAME)

and all clauses of the form

     
     (static EXPRESSION ...)

all additionally inserted into the expansion.

As a convenience, the clause

     
     (export IDENTIFIER ...)

is also allowed and is identical to (declare (export IDENTIFIER ...)) (unless the define-extension form occurs in interpreted code, in with it is simply ignored).

Note that the compiler option -extension NAME is equivalent to prefixing the compiled file with

          (define-extension NAME)
     

— syntax: :optional

          (: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

          (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 the documentation for SRFI-16

— syntax: let-optionals
— syntax: let-optionals*

          (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)
          (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, otherwise 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: and-let*

          (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 the documentation for SRFI-2.

— syntax: rec

          (rec NAME EXPRESSION)
          (rec (NAME VARIABLE ...) BODY ...)
     

Allows simple definition of recursive definitions. (rec NAME EXPRESSION) is equivalent to (letrec ((NAME EXPRESSION)) NAME) and (rec (NAME VARIABLE ...) BODY ...) is the same as (letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME).

— syntax: cut
— syntax: cute

          (cut SLOT ...)
          (cute SLOT ...)
     

Syntactic sugar for specializing parameters.

— syntax: define-values

          (define-values (NAME ...) EXP)
     

Defines several variables at once, with the result values of expression EXP.

— syntax: fluid-let

          (fluid-let ((VAR1 X1) ...) BODY ...)
     

Binds the variables VAR1 ... dynamically to the values X1 ... during execution of BODY ....

— syntax: let-values

          (let-values (((NAME ...) EXP) ...) BODY ...)
     

Binds multiple variables to the result values of EXP .... All variables are bound simultaneously.

— syntax: let*-values

          (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

          (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

          (parameterize ((PARAMETER1 X1) ...) BODY ...)
     

Binds the parameters PARAMETER1 ... dynamically to the values X1 ... during execution of BODY .... (see also: make-parameter in Parameters). Note that PARAMETER may be any expression that evaluates to a parameter procedure.

— syntax: receive

          (receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
          (receive VALUEEXP)
     

SRFI-8. Syntactic sugar for call-with-values. Binds variables to the result values of VALUEEXP and evaluates BODY ....

The syntax

     
     (receive VALUEEXP)

is equivalent to

     
     (receive _ VALUEEXP _)

— syntax: set!-values

          (set!-values (NAME ...) EXP)
     

Assigns the result values of expression EXP to multiple variables.

— syntax: define-constant

          (define-constant NAME CONST)
     

Define a variable with a constant value, evaluated at compile-time. Any reference to such a constant should appear textually after its 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. CONST may be any constant expression, and may also refer to constants defined via define-constant previously. This for should only be used at top-level.

— syntax: define-inline

          (define-inline (NAME VAR ... [. VAR]) BODY ...)
          (define-inline 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 its 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.

— syntax: define-macro

          (define-macro (NAME VAR ... [. VAR]) EXP1 ...)
          (define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
          (define-macro NAME1 NAME2)
     

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 and the declaration run-time-macros (or the command line option -run-time-macros) has been used, 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 or a macro name. Only global macros can be defined using this form. (define-macro NAME1 NAME2) simply copies the macro definition from NAME2 to NAME1, creating an alias.

Extended lambda list syntax (#!optional, etc.) can be used but note that arguments are source expressions and thus default values for optional or keyword arguments should take this into consideration.

— syntax: define-for-syntax

          (define-for-syntax (NAME VAR ... [. VAR]) EXP1 ...)
          (define-for-syntax NAME [VALUE])
     

Defines the toplevel variable NAME at macro-expansion time. This can be helpful when you want to define support procedures for use in macro-transformers, for example.

— syntax: switch

          (switch EXP (KEY EXP1 ...) ... [(else EXPn ...)])
     

This is similar to case, but a) only a single key is allowed, and b) the key is evaluated.

— syntax: unless

          (unless TEST EXP1 EXP2 ...)
     

Equivalent to:

     
     (if (not TEST) (begin EXP1 EXP2 ...))

— syntax: when

          (when TEST EXP1 EXP2 ...)
     

Equivalent to:

     
     (if TEST (begin EXP1 EXP2 ...))

— syntax: define-record

          (define-record NAME SLOTNAME ...)
     

Defines a record type. 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

          (define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)
          (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

define-record-printer works also with SRFI-9 record types.

— syntax: define-record-type

          (define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE
                              (FIELD ACCESSOR [MODIFIER]) ...)
     

SRFI-9 record types. For more information see the documentation for SRFI-9.

— syntax: assert

          (assert EXP [STRING ARG ...])
     

Signals an error if EXP evaluates to false. An optional message STRING and arguments ARG ... may be supplied to give a more informative error-message. If compiled in unsafe mode (either by specifying the -unsafe compiler option or by declaring (unsafe)), then this expression expands to an unspecified value. The result is the value of EXP.

— syntax: cond-expand

          (cond-expand FEATURE-CLAUSE ...)
     

SRFI-0. Expands by selecting feature clauses. Predefined feature-identifiers are srfi-0, srfi-2, srfi-6, srfi-8, srfi-9, srfi-10, and chicken. If the source file containing this form is currently compiled, the feature compiling is defined. For further information, see the documentation for SRFI-0 This form is allowed to appear in non-toplevel expressions.

— syntax: critical-section

          (critical-section BODY ...)
     

Evaluate BODY ... with timer-interrupts temporarily disabled.

— syntax: ensure

          (ensure PREDICATE EXP [ARGUMENTS ...])
     

Evaluates the expression EXP and applies the one-argument procedure PREDICATE to the result. If the predicate returns #f an error is signaled, otherwise the result of EXP is returned. If compiled in unsafe mode (either by specifying the -unsafe compiler option or by declaring (unsafe)), then this expression expands to an unspecified value. If specified, the optional ARGUMENTS are used as arguments to the invocation of the error-signalling code, as in (error ARGUMENTS ...). If no ARGUMENTS are given, a generic error message is displayed with the offending value and PREDICATE expression.

— syntax: eval-when

          (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 while compiling code, and the situation specifier compile is given, then this form is evaluated at compile-time. When encountered while compiling 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.

The following table should make this clearer:

	in compiled code	In interpreted code
eval	ignore	evaluate
compile	evaluate at compile time	ignore
load	compile as normal	ignore

The situation specifiers compile-time and run-time are also defined and have the same meaning as compile and load, respectively.

— syntax: include

          (include STRING)
     

Include toplevel-expressions from the 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.

— syntax: nth-value

          (nth-value N EXP)
     

Returns the Nth value (counting from zero) of the values returned by expression EXP.

— syntax: time

          (time EXP1 ...)
     

Evaluates EXP1 ... and prints elapsed time and some values about GC use, like time spent in major GCs, number of minor and major GCs.

     (match exp [pat body] ...)

     (define map
       (lambda (f l)
         (match l
           [() ()]
           [(x . y) (cons (f x) (map f y))])))

exp ::= (match exp clause ...)
     |  (match-lambda clause ...)
     |  (match-lambda* clause ...)
     |  (match-let ([pat exp] ...) body)
     |  (match-let* ([pat exp] ...) body)
     |  (match-letrec ([pat exp] ...) body)
     |  (match-let var ([pat exp] ...) body)
     |  (match-define pat exp)

clause ::= [pat body]
        |  [pat (=> identifier) body]

pat ::= identifier           matches anything, and binds identifier as a variable
     |  _                    anything
     |  ()                   itself (the empty list)
     |  #t                   itself
     |  #f                   itself
     |  string               an `equal?' string
     |  number               an `equal?' number
     |  character            an `equal?' character
     |  's-expression        an `equal?' s-expression
     |  (pat-1 ... pat-n)    a proper list of n elements
     |  (pat-1 ... pat-n . pat-n+1)  
                             a list of n or more elements
     |  (pat-1 ... pat-n pat-n+1 ..k)  
                             a proper list of n+k or more elements [1]
     |  #(pat-1 ... pat-n)   a vector of n elements
     |  #(pat-1 ... pat-n pat-n+1 ..k)  
                             a vector of n+k or more elements
     |  ($ struct pat-1 ... pat-n)  
                             a structure
     |  (= field pat)        a field of a structure
     |  (and pat-1 ... pat-n)  
                             if all of pat-1 through pat-n match
     |  (or pat-1 ... pat-n) 
                             if any of pat-1 through pat-n match
     |  (not pat-1 ... pat-n)
                             if none of pat-1 through pat-n match
     |  (? predicate pat-1 ... pat-n)  
                             if predicate true and pat-1 through pat-n all match
     |  (set! identifier)    anything, and binds identifier as a setter
     |  (get! identifier)    anything, and binds identifier as a getter
     |  `qp                  a quasipattern

qp ::= ()                    itself (the empty list)
    |  #t                    itself
    |  #f                    itself
    |  string                an `equal?' string
    |  number                an `equal?' number
    |  character             an `equal?' character
    |  symbol                an `equal?' symbol
    |  (qp-1 ... qp-n)       a proper list of n elements
    |  (qp-1 ... qp-n . qp-n+1)  
                             a list of n or more elements
    |  (qp-1 ... qp-n qp-n+1 ..k)  
                             a proper list of n+k or more elements
    |  #(qp-1 ... qp-n)      a vector of n elements
    |  #(qp-1 ... qp-n qp-n+1 ..k)  
                             a vector of n+k or more elements
    |  ,pat                  a pattern
    |  ,@pat                 a pattern, spliced

     (match-lambda [pat body] ...)   =  (lambda (x) (match x [pat body] ...))
     (match-lambda* [pat body] ...)  =  (lambda x (match x [pat body] ...))

     (match-let ([(x y z) (list 1 2 3)]) body ...)

     (match '(let ([x 1][y 2]) z)
       [('let ((binding values) ...) exp)  body])

     (define x (list 1 (list 2 3)))
     (match x [(_ (_ (set! setit)))  (setit 4)])

#;1> (match 1 (2 2))

Failed match:
Error: no matching clause for : 1

— procedure: match-error-control

          (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.

When an error is signalled, the raised exception will be of kind (exn match).

     null? pair? number? string? symbol? boolean? char? procedure? vector? list?
     equal?
     car cdr cadr cdddr ...
     vector-length vector-ref
     reverse length call/cc

— syntax: declare

          (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. Declarations are ignored in the interpreter but not in code evaluated at compile-time (by eval-when or in syntax extensions loaded via require-extension or require-for-syntax. DECLSPEC may be any of the following:

— declaration specifier: always-bound

               (always-bound SYMBOL ...)
          

Declares that the given variables are always bound and accesses to those have not to be checked.

— declaration specifier: block

               (block)
          

Assume global variables are never redefined. This is the same as specifying the -block option.

— declaration specifier: block-global
— declaration specifier: hide

               (block-global SYMBOL ...)
               (hide SYMBOL ...)
          

Declares that the toplevel bindings for SYMBOL ... should not be accessible from code in other compilation units or by eval. Access to toplevel bindings declared as block global is also more efficient.

— declaration specifier: bound-to-procedure

               (bound-to-procedure SYMBOL ...)
          

Declares that the given identifiers are always bound to procedure values.

— declaration specifier: c-options

               (c-options STRING ...)
          

Declares additional C/C++ compiler options that are to be passed to the subsequent compilation pass that translates C to machine code. This declaration will only work if the source file is compiled with the csc compiler driver.

— declaration specifier: check-c-syntax

               (check-c-syntax)
               (not check-c-syntax)
          

Enables or disables syntax-checking of embedded C/C++ code fragments. Checking C syntax is the default.

— declaration specifier: compress-literals

               (compress-literals [THRESHOLD [INITIALIZER]])
          

The same as the -compress-literals compiler option. The threshold argument defaults to 50. If the optional argument INITIALIZER is given, then the literals will not be created at module startup, but when the procedure with this name will be called.

— declaration specifier: export

               (export SYMBOL ...)
          

The opposite of hide. All given identifiers will be exported and all toplevel variables not listed will be hidden and not be accessible outside of this compilation unit.

— declaration specifier: emit-external-prototypes-first

               (emit-external-prototypes-first)
          

Emit prototypes for callbacks defined with define-external before any other foreign declarations. Equivalent to giving the -emit-external-prototypes-first option to the compiler.

— declaration specifier: disable-interrupts

               (disable-interrupts)
               (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: inline

               (inline)
               (not inline)
               (inline IDENTIFIER ...)
               (not inline IDENTIFIER ...)
          

If given without an identifier-list, inlining of known procedures is enabled (this is equivalent to the -inline compiler option). When an identifier-list is given, then inlining is enabled only for the specified global procedures. The negated forms (not inline) and (not inline IDENTIFIER) disable global inlining, or inlining for the given global procedures only, respectively.

— declaration specifier: inline-limit

               (inline-limit THRESHOLD)
          

Sets the maximum size of procedures which may potentially be inlined. The default threshold is 10.

— declaration specifier: interrupts-enabled

               (interrupts-enabled)
          

Enable timer-interrupts checks in the compiled program (the default).

— declaration specifier: lambda-lift

               (lambda-lift)
          

Enables lambda-lifting (equivalent to the -lambda-lift option).

— declaration specifier: link-options

               (link-options STRING ...)
          

Declares additional linker compiler options that are to be passed to the subsequent compilation pass that links the generated code into an executable or library. This declaration will only work if the source file is compiled with the csc compiler driver.

— declaration specifier: no-argc-checks

               (no-argc-checks)
          

Disables argument count checking.

— declaration specifier: no-bound-checks

               (no-bound-checks)
          

Disables the bound-checking of toplevel bindings.

— declaration specifier: no-procedure-checks

               (no-procedure-checks)
          

Disables checking of values in operator position for being of procedure type.

— declaration specifier: post-process

               (post-process STRING ...)
          

Arranges for the shell commands STRING ... to be invoked after the current file has been translated to C. Any occurrences of the substring $@ in the strings given for this declaration will be replaced by the pathname of the currently compiled file, without the file-extension. This declaration will only work if the source file is compiled with the csc compiler driver.

— declaration specifier: TYPE
— declaration specifier: fixnum-arithmetic

               ([number-type] TYPE)
               (fixnum-arithmetic)
          

Declares that only numbers of the given type are used. TYPE may be fixnum or generic (which is the default).

— declaration specifier: run-time-macros

               (run-time-macros)
          

Equivalent to the compiler option of the same name - macros defined in the compiled code are also made available at runtime.

— declaration specifier: standard-bindings

               (standard-bindings SYMBOL ...)
               (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: extended-bindings

               (extended-bindings SYMBOL ...)
               (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: usual-integrations

               (usual-integrations SYMBOL ...)
               (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. Note that this is the default behaviour, unless the -no-usual-integrations option has been given.

— declaration specifier: unit

               (unit SYMBOL)
          

Specify compilation unit-name (if this is a library)

— declaration specifier: unsafe

               (unsafe)
               (not safe)
          

Do not generate safety-checks. This is the same as specifying the -unsafe option. Also implies

          
          (declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))
     

— declaration specifier: uses

               (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.

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

— procedure: make-parameter

          (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 its 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.

— parameter: case-sensitive

If true, then read reads symbols and identifiers in case-sensitive mode and uppercase characters in symbols are printed escaped. Defaults to #t.

— parameter: dynamic-load-libraries

A list of strings containing shared libraries that should be checked for explicitly loaded library units (this facility is not available on all platforms). See load-library.

— parameter: command-line-arguments

Contains the list of arguments passed to this program, with the name of the program and any runtime options (all options starting with -:) removed.

— parameter: current-read-table

A read-table object that holds read-procedures for special non-standard read-syntax (see set-read-syntax! for more information).

— 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 behavior 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 behavior is to evaluate the argument expression and to ignore the second parameter.

— parameter: force-finalizers

If true, force and execute all pending finalizers before exiting the program (either explicitly by exit or implicitly when the last toplevel expression has been executed). Default is #t.

— 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 invoke all pending finalizers.

— parameter: keyword-style

Enables alternative keyword syntax, where STYLE may be either #:prefix (as in Common Lisp) or #:suffix (as in DSSSL). Any other value disables the alternative syntaxes.

— parameter: load-verbose

A boolean indicating whether loading of source files, compiled code (if available) and compiled libraries should display a message.

— parameter: repl-prompt

A procedure that should evaluate to a string that will be printed before reading interactive input from the user in a read-eval-print loop. Defaults to (lambda () "#;N> ").

— parameter: reset-handler

A procedure of zero arguments that is called via reset. The default behavior in compiled code is to invoke the value of (exit-handler). The default behavior in the interpreter is to abort the current computation and to restart the read-eval-print loop.

— procedure: add1
— procedure: sub1

          (add1 N)
          (sub1 N)
     

Adds/subtracts 1 from N.

— procedure: bitwise-and
— procedure: bitwise-ior
— procedure: bitwise-xor
— procedure: bitwise-not
— procedure: arithmetic-shift

          (bitwise-and N1 ...)
          (bitwise-ior N1 ...)
          (bitwise-xor N1 ...)
          (bitwise-not N)
          (arithmetic-shift N1 N2)
     

Binary integer operations. arithmetic-shift shifts the argument N1 by N2 bits to the left. If N2 is negative, than N1 is shifted to the right. These operations only accept exact integers or inexact integers in word range (32 bit signed on 32-bit platforms, or 64 bit signed on 64-bit platforms).

— procedure: fixnum?

          (fixnum? X)
     

Returns #t if X is a fixnum, or #f otherwise.

— procedure: fx+
— procedure: fx-
— procedure: fx*
— procedure: fx/
— procedure: fxmod
— procedure: fxneg
— procedure: fxmin
— procedure: fxmax
— procedure: fx=
— procedure: fx>
— procedure: fx<
— procedure: fx>=
— procedure: fx<=
— procedure: fxand
— procedure: fxior
— procedure: fxxor
— procedure: fxnot
— procedure: fxshl
— procedure: fxshr

          (fx+ N1 N2)
          (fx- N1 N2)
          (fx* N1 N2)
          (fx/ N1 N2)
          (fxmod N1 N2)
          (fxneg N)
          (fxmin N1 N2)
          (fxmax N1 N2)
          (fx= N1 N2)
          (fx> N1 N2)
          (fx< N1 N2)
          (fx>= N1 N2)
          (fx<= N1 N2)
          (fxand N1 N2)
          (fxior N1 N2)
          (fxxor N1 N2)
          (fxnot N)
          (fxshl N1 N2)
          (fxshr 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.

On division by zero, fx/ and fxmod signal a condition of kind (exn arithmetic).

fxshl and fxshr perform arithmetic shift left and right, respectively.

— procedure: fp+
— procedure: fp-
— procedure: fp*
— procedure: fp/
— procedure: fpneg
— procedure: fpmin
— procedure: fpmax
— procedure: fp=
— procedure: fp>
— procedure: fp<
— procedure: fp>=
— procedure: fp<=

          (fp+ N1 N2)
          (fp- N1 N2)
          (fp* N1 N2)
          (fp/ N1 N2)
          (fpneg N)
          (fpmin N1 N2)
          (fpmax N1 N2)
          (fp= N1 N2)
          (fp> N1 N2)
          (fp< N1 N2)
          (fp>= N1 N2)
          (fp<= N1 N2)
     

Arithmetic floating-point operations. These procedures do not check their arguments, so non-flonum parameters will result in incorrect results. On division by zero, fp/ signals a condition of kind (exn arithmetic).

— procedure: signum

          (signum N)
     

Returns 1 if N is positive, -1 if N is negative or 0 if N is zero. signum is exactness preserving.

— procedure: current-error-port

          (current-error-port [PORT])
     

Returns default error output port. If PORT is given, then that port is selected as the new current error output port.

— procedure: flush-output

          (flush-output [PORT])
     

Write buffered output to the given output-port. PORT defaults to the value of (current-output-port).

— procedure: port-name

          (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 parentheses for non-file ports.

— procedure: port-position

          (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.

— procedure: set-port-name!

          (set-port-name! PORT STRING)
     

Sets the name of PORT to STRING.

— procedure: delete-file

          (delete-file STRING)
     

Deletes the file with the pathname STRING. If the file does not exist, an error is signaled.

— procedure: file-exists?

          (file-exists? STRING)
     

Returns STRING if a file with the given pathname exists, or #f otherwise.

— procedure: rename-file

          (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.

— procedure: get-output-string

          (get-output-string PORT)
     

Returns accumulated output of a port created with (open-output-string).

— procedure: open-input-string

          (open-input-string STRING)
     

Returns a port for reading from STRING.

— procedure: open-output-string

          (open-output-string)
     

Returns a port for accumulating output in a string.

— procedure: features

          (features)
     

Returns a list of all registered features that will be accepted as valid feature-identifiers by cond-expand.

— procedure: test-feature?

          (test-feature? ID ...)
     

Returns #t if all features with the given feature-identifiers ID ... are registered.

— procedure: register-feature!

          (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!

          (unregister-feature! FEATURE ...)
     

Unregisters the specified feature-identifiers. FEATURE ... may be a keyword, string or symbol.

— procedure: get-keyword

          (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 #:amount args (lambda () 1))) )
     (increase 123)                                      ==> 124
     (increase 123 #:amount 10)                          ==> 133

Note: the KEYWORD may actually be any kind of object.

— procedure: keyword?

          (keyword? X)
     

Returns #t if X is a keyword symbol, or #f otherwise.

— procedure: keyword->string

          (keyword->string KEYWORD)
     

Transforms KEYWORD into a string.

— procedure: string->keyword

          (string->keyword STRING)
     

Returns a keyword with the name STRING.

— syntax: condition-case

          (condition-case EXPRESSION CLAUSE ...)
     

Evaluates EXPRESSION and handles any exceptions that are covered by CLAUSE ..., where CLAUSE should be of the following form:

     
     CLAUSE = ([VARIABLE] (KIND ...) BODY ...)

If provided, VARIABLE will be bound to the signalled exception object. BODY ... is executed when the exception is a property- or composite condition with the kinds given KIND ... (unevaluated). If no clause applies, the exception is re-signalled in the same dynamic context as the condition-case form.

     
     (define (check thunk)
       (condition-case (thunk)
         [(exn file) (print "file error")]
         [(exn) (print "other error")]
         [var () (print "something else")] ) )
     
     (check (lambda () (open-input-file "")))   ; -> "file error"
     (check (lambda () some-unbound-variable))  ; -> "othererror"
     (check (lambda () (signal 99)))            ; -> "something else"
     
     (condition-case some-unbound-variable
       [(exn file) (print "ignored)] )      ; -> signals error
     

— procedure: argv

          (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 whether arguments are expanded ('globbed') or not.

— procedure: exit

          (exit [CODE])
     

Exit the running process and return exit-code, which defaults to 0 (Invokes exit-handler).

— procedure: build-platform

          (build-platform)
     

Returns a symbol specifying the toolset which has been used for building the executing system, which is one of the following:

     
     cygwin
     msvc
     mingw32
     gnu
     metrowerks
     intel
     watcom
     unknown

— procedure: chicken-version

          (chicken-version [FULL])
     

Returns a string containing the version number of the CHICKEN runtime system. If the optional argument FULL is given and true, then a full version string is returned.

— procedure: errno

          (errno)
     

Returns the error code of the last system call.

— procedure: getenv

          (getenv STRING)
     

Returns the value of the environment variable STRING or #f if that variable is not defined.

— procedure: machine-type

          (machine-type)
     

Returns a symbol specifying the processor on which this process is currently running, which is one of the following:

     
     alpha
     mips
     hppa
     ultrasparc
     sparc
     ppc
     ia64
     x86
     x86-64
     unknown

— procedure: software-type

          (software-type)
     

Returns a symbol specifying the operating system on which this process is currently running, which is one of the following:

     
     windows
     unix
     macos
     ecos
     unknown

— procedure: software-version

          (software-version)
     

Returns a symbol specifying the operating system version on which this process is currently running, which is one of the following:

     
     linux
     freebsd
     netbsd
     openbsd
     macosx
     hpux
     solaris
     sunos
     unknown

— procedure: c-runtime

          (c-runtime)
     

Returns a symbol that designates what kind of C runtime library has been linked with this version of the Chicken libraries. Possible return values are static, dynamic or unknown. On systems not compiled with the Microsoft C compiler, c-runtime always returns unknown.

— procedure: chicken-home

          (chicken-home)
     

Returns a string given the installation directory (usually /usr/local/share/chicken on UNIX-like systems). If the environment variable CHICKEN_HOME is set, then its value will be returned.

— procedure: system

          (system STRING)
     

Execute shell command. The functionality offered by this procedure depends on the capabilities of the host shell.

— procedure: cpu-time

          (cpu-time)
     

Returns the used CPU time of the current process in milliseconds as two values: the time spent in user code, and the time spent in system code. On platforms where user and system time can not be differentiated, system time will be always be 0.

— procedure: current-milliseconds

          (current-milliseconds)
     

Returns the number of milliseconds since process- or machine startup.

— procedure: current-seconds

          (current-seconds)
     

Returns the number of seconds since midnight, Jan. 1, 1970.

— procedure: current-gc-milliseconds

          (current-gc-milliseconds)
     

Returns the number of milliseconds spent in major garbage collections since the last call of current-gc-milliseconds and returns an exact integer.

— procedure: enable-interrupts
— procedure: disable-interrupts

          (enable-interrupts)
          (disable-interrupts)
     

Enables/disables processing of timer-interrupts and interrupts caused by signals.

     
     (disable-interrupts)
     (disable-interrupts)
     (enable-interrupts)
     ; <interrupts still disabled - call enable-interrupts once more>

— procedure: enable-warnings

          (enable-warnings [BOOL])
     

Enables or disables warnings, depending on wether BOOL is true or false. If called with no arguments, this procedure returns #t if warnings are currently enabled, or #f otherwise. Note that this is not a parameter. The current state (wether warnings are enabled or disabled) is global and not thread-local.

— procedure: error

          (error [LOCATION] 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. If LOCATION is given and a symbol, it specifies the “location” (the name of the procedure) where the error occurred.

— procedure: get-call-chain

          (get-call-chain [START [THREAD]])
     

Returns a list with the call history. Backtrace information is only generated in code compiled without -no-trace and evaluated code. If the optional argument START is given, the backtrace starts at this offset, i.e. when START is 1, the next to last trace-entry is printed, and so on. If the optional argument THREAD is given, then the call-chain will only be constructed for calls performed by this thread.

— procedure: print-call-chain

          (print-call-chain [PORT [START [THREAD]]])
     

Prints a backtrace of the procedure call history to PORT, which defaults to (current-error-port).

— procedure: print-error-message

          (print-error-message EXN [PORT [STRING]])
     

Prints an appropriate error message to PORT (which defaults to the value of (current-output-port) for the object EXN. EXN may be a condition, a string or any other object. If the optional argument STRING is given, it is printed before the error-message. STRING defaults to "Error:".

— procedure: procedure-information

          (procedure-information PROC)
     

Returns an s-expression with debug information for the procedure PROC, or #f, if PROC has no associated debug information.

— procedure: reset

          (reset)
     

Reset program (Invokes reset-handler).

— procedure: warning

          (warning STRING EXP ...)
     

Displays a warning message (if warnings are enabled with enable-warnings) and continues execution.

— procedure: gc

          (gc [FLAG])
     

Invokes a garbage-collection and returns the number of free bytes in the heap. The flag specifies whether a minor (#f) or major (#t) GC is to be triggered. If no argument is given, #t is assumed. When the argument is #t, all pending finalizers are executed. 

— procedure: memory-statistics

          (memory-statistics)
     

Performs a major garbage collection and returns a three element vector containing the total heap size in bytes, the number of bytes currently used and the size of the nursery (the first heap generation). Note that the actual heap is actually twice the size given in the heap size, because CHICKEN uses a copying semi-space collector.

— procedure: set-finalizer!

          (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 its argument). Note that the finalizer will not be called when interrupts are disabled. This procedure returns X.

— procedure: set-gc-report!

          (set-gc-report! FLAG)
     

Print statistics after every GC, depending on FLAG. A value of #t shows statistics after every major GC. A true value different from #t shows statistics after every minor GC. #f switches statistics off.

— procedure: andmap

          (andmap PROC LIST1 ...)
     

Repeatedly calls PROC with arguments taken from LIST1 .... If any invocation should return #f, the result of andmap is #f. If all invocations return a true result, then the result of andmap is #t.

— procedure: ormap

          (ormap PROC LIST1 ...)
     

Repeatedly calls PROC with arguments taken from LIST1 .... If any invocation should return a value different from #f, then this value is returned as the result of ormap. If all invocations return #f, then the result of ormap is #f.

— procedure: promise?

          (promise? X)
     

Returns #t if X is a promise returned by delay, or #f otherwise.

— procedure: reverse-list->string

          (reverse-list->string LIST)
     

Returns a string with the characters in LIST in reverse order. This is equivalent to (list->string (reverse LIST)), but much more efficient.

— procedure: gensym

          (gensym [STRING-OR-SYMBOL])
     

Returns a newly created uninterned symbol. If an argument is provided, the new symbol is prefixed with that argument.

— procedure: string->uninterned-symbol

          (string->uninterned-symbol STRING)
     

Returns a newly created, unique symbol with the name STRING.

— procedure: port?

          (port? X)
     

Returns #t if X is a port object or #f otherwise.

— procedure: print

          (print EXP1 EXP2 ...)
     

Outputs the arguments EXP1 EXP2 ... using display and writes a newline character to the port that is the value of (current-output-port). Returns its first argument.

— procedure: print*

          (print* EXP1 ...)
     

Similar to print, but does not output a terminating newline character and performes a flush-outout after writing its arguments.

— procedure: char-name

          (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 behavior 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: vector-copy!

          (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. If not given, the minimum of the lengths of the argument vectors is copied.

Exceptions: (exn bounds)

— procedure: vector-resize

          (vector-resize VECTOR N [INIT])
     

Creates and returns a new vector with the contents of VECTOR and length N. If N is greater than the original length of VECTOR, then all additional items are initialized to INIT. If INIT is not specified, the contents are initialized to some unspecified value.

— procedure: void

          (void)
     

Returns an unspecified value.

— procedure: call/cc

          (call/cc PROCEDURE)
     

An alias for call-with-current-continuation.

— procedure: continuation-capture

          (continuation-capture PROCEDURE)
     

Creates a continuation object representing the current continuation and tail-calls PROCEDURE with this continuation as the single argument.

More information about this continuation API can be found in the paper http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf “A Better API for first class Continuations” by marc Feeley.

— procedure: continuation?

          (continuation? X)
     

Returns #t if X is a continuation object, or #f otherwise.

— procedure: continuation-graft

          (continuation-graft CONT THUNK)
     

Calls the procedure THUNK with no arguments and the implicit continuation CONT.

— procedure: continuation-return

          (continuation-return CONT VALUE ...)
     

Returns the value(s) to the continuation CONT. continuation-result could be implemented like this:

          (define (continuation-return k . vals)
            (continuation-graft
              k
              (lambda () (apply values vals)) ) )
     

— procedure: setter

          (setter PROCEDURE)
     

Returns the setter-procedure of PROCEDURE, or signals an error if PROCEDURE has no associated setter-procedure.

Note that (set! (setter PROC) ...) for a procedure that has no associated setter procedure yet is a very slow operation (the old procedure is replaced by a modified copy, which involves a garbage collection).

— procedure: getter-with-setter

          (getter-with-setter GETTER SETTER)
     

Returns a copy of the procedure GETTER with the associated setter procedure SETTER. Contrary to the SRFI specification, the setter of the returned procedure may be changed.

— procedure: load

          (load FILE [EVALPROC])
     

Loads and evaluates expressions from the given source file, which may be either a string or an input port. Each expression read is passed to EVALPROC (which defaults to eval). On platforms that support it (currently native Windows, Linux ELF and Solaris), load can be used to load compiled programs:

     
     % cat x.scm
     (define (hello) (print "Hello!"))
     % csc -s x.scm
     % csi -q
     #;1> (load "x.so")
     ; loading x.so ...
     #;2> (hello)
     Hello!
     #;3>

The second argument to load is ignored when loading compiled code. If source code is loaded from a port, then that port is closed after all expressions have been read.

Compiled code can be re-loaded, but care has to be taken, if code from the replaced dynamically loaded module is still executing (i.e. if an active continuation refers to compiled code in the old module).

Support for realoding compiled code dynamically is still experimental.

— procedure: load-library

          (load-library UNIT [LIBRARYFILE])
     

On platforms that support dynamic loading, load-library loads the compiled library unit UNIT (which should be a symbol). If the string LIBRARYFILE is given, then the given shared library will be loaded and the toplevel code of the contained unit will be executed. If no LIBRARYFILE argument is given, then the following libraries are checked for the required unit:

• a file named “<UNIT>.so”
• the files given in the parameter dynamic-load-libraries

If the unit is not found, an error is signaled. When the library unit can be successfully loaded, a feature-identifier named UNIT is registered. If the feature is already registered before loading, the load-library does nothing.

— procedure: load-noisily

          (load-noisily FILE #!key EVALUATOR TIME PRINTER)
     

As load but the result(s) of each evaluated toplevel-expression is written to standard output. If EVALUATOR is given and not #f, then each expression is evaluated by calling this argument with the read expression as argument. If TIME is given and not false, then the execution time of each expression is shown (as with the time macro). If PRINTER is given and not false, then each expression is printed before evaluation by applying the expression to the value of this argument, which should be a one-argument procedure.

— procedure: set-dynamic-load-mode!

          (set-dynamic-load-mode! MODELIST)
     

On systems that support dynamic loading of compiled code via the dlopen(3) interface (for example Linux and Solaris), some options can be specified to fine-tune the behaviour of the dynamic linker. MODE should be a list of symbols (or a single symbol) taken from the following set:

• local If local is given, then any C/C++ symbols defined in the dynamically loaded file are not available for subsequently loaded files and libraries. Use this if you have linked foreign code into your dynamically loadable file and if you don't want to export them (for example because you want to load another file that defines the same symbols).
• global The default is global, which means all C/C++ symbols are available to code loaded at a later stage.
• now If now is specified, all symbols are resolved immediately.
• lazy Unresolved symbols are resolved as code from the file is executed. This is the default.

Note that this procedure does not control the way Scheme variables are handled - this facility is mainly of interest when accessing foreign code.

— procedure: repl

          (repl)
     

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.

— procedure: get-line-number

          (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?

          (macro? SYMBOL)
     

Returns #t if there exists a macro-definition for SYMBOL.

— procedure: macroexpand

          (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

          (macroexpand-1 X)
     

If X is a macro-form, expand the macro. Returns the resulting expression.

— procedure: undefine-macro!

          (undefine-macro! SYMBOL)
     

Remove the current macro-definition of the macro named SYMBOL.

— procedure: syntax-error

          (syntax-error [LOCATION] MESSAGE ARGUMENT ...)
     

Signals an exception of the kind (exn syntax). Otherwise identical to error.

— parameter: repository-path

Contains a string naming the path to the extension repository, which defaults to either the value of the environment variable CHICKEN_REPOSITORY, the value of the environment variable CHICKEN_HOME or the default library path (usually /usr/local/lib/chicken on UNIX systems).

— procedure: extension-information

          (extension-information ID)
     

If an extension with the name ID is installed and if it has a setup-information list registered in the extension repository, then the info-list is returned. Otherwise extension-information returns #f.

— procedure: provide

          (provide ID ...)
     

Registers the extension IDs ID ... as loaded. This is mainly intended to provide aliases for certain extension identifiers.

— procedure: provided?

          (provided? ID ...)
     

Returns #t if the extension with the IDs ID ... are currently loaded, or #f otherwise. Works also for feature-ids.

— procedure: require
— procedure: require-for-syntax

          (require ID ...)
          (require-for-syntax ID ...)
     

If the extension library ID is not already loaded into the system, then require will lookup the location of the shared extension library and load it. If ID names a library-unit of the base system, then it is loaded via load-library. If no extension library is available for the given ID, then an attempt is made to load the file ID.so or ID.scm (in that order) from one of the following locations:

1. the current include path, which defaults to the pathnames given in CHICKEN_INCLUDE_PATH and CHICKEN_HOME.
2. the current directory

ID should be a string or a symbol. The difference between require and require-for-syntax is the the latter loads the extension library at compile-time (the argument is still evaluated), while the former loads it at run-time.

— procedure: set-extension-specifier!

          (set-extension-specifier! SYMBOL PROC)
     

Registers the handler-procedure PROC as a extension-specifier with the name SYMBOL. This facility allows extending the set of valid extension specifiers to be used with require-extension. When register-extension is called with an extension specifier of the form (SPEC ...) and SPEC has been registered with set-extension-specifier!, then PROC will be called with two arguments: the specifier and the previously installed handler (or #f if no such handler was defined). The handler should return a new specifier that will be processed recursively. If the handler returns a vector, then each element of the vector will be processed recursively. Alternatively the handler may return a string which specifies a file to be loaded:

          (eval-when (compile eval)
            (set-extension-specifier!
              'my-package
              (lambda (spec old)
                (make-pathname my-package-directory (->string (cadr spec))) ) ) )
          
          (require-extension (my-package stuff))     ; --> expands into '(load "my-package-dir/stuff")
     

Note that the handler has to be registered at compile time, if it is to be visible in compiled code.

— procedure: define-reader-ctor

          (define-reader-ctor SYMBOL PROC)
     

Define new read-time constructor for #, read syntax. For further information, see the documentation for SRFI-10.

— procedure: set-read-syntax!

          (set-read-syntax! CHAR PROC)
     

When the reader is encounting the non-whitespace character CHAR while reading an expression from a given port, then the procedure PROC will be called with that port as its argument. The procedure should return a value that will be returned to the reader:

          ; A simple RGB color syntax:
          
          (set-read-syntax! #\%
            (lambda (port)
              (apply vector
                (map (cut string->number <> 16)
                     (string-chop (read-string 6 port) 2) ) ) ) )
          
          (with-input-from-string "(1 2 %f0f0f0 3)" read)
          ; ==> (1 2 #(240 240 240) 3)
     

You can undo special handling of read-syntax by passing #f as the second argument (if the syntax was previously defined via set-read-syntax!).

Note that all of CHICKEN's special non-standard read-syntax is handled directly by the reader to disable built-in read-syntax, define a handler that triggers an error (for example).

— procedure: set-sharp-read-syntax!

          (set-sharp-read-syntax! CHAR PROC)
     

Similar to set-read-syntax!, but allows defining new #<CHAR> ... reader syntax.

— procedure: copy-read-table

          (copy-read-table READ-TABLE)
     

Returns a copy of the given read-table. You can access the currently active read-table with (current-read-table).

— procedure: eval

          (eval EXP [ENVIRONMENT])
     

Evaluates EXP and returns the result of the evaluation. The second argument is optional and defaults to the value of (interaction-environment).

— procedure: alist-ref

          (alist-ref KEY ALIST [TEST [DEFAULT]])
     

Looks up KEY in ALIST using TEST as the comparison function (or eqv? if no test was given) and returns the cdr of the found pair, or DEFAULT (which defaults to #f).

— procedure: alist-update!

          (alist-update! KEY VALUE ALIST [TEST])
     

If the list ALIST contains a pair of the form (KEY . X), then this procedure replaces X with VALUE and returns ALIST. If ALIST contains no such item, then alist-update! returns ((KEY . VALUE) . ALIST). The optional argument TEST specifies the comparison procedure to search a matching pair in ALIST and defaults to eqv?.

— procedure: atom?

          (atom? X)
     

Returns #t if X is a not list (X is not a pair nor the empty list).

— procedure: rassoc

          (rassoc KEY LIST [TEST])
     

Similar to assoc, but compares KEY with the cdr of each pair in LIST using TEST as the comparison procedures (which defaults to eqv?.

— procedure: butlast

          (butlast LIST)
     

Returns a fresh list with all elements but the last of LIST.

— procedure: chop

          (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

          (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

          (flatten LIST1 ...)
     

Returns LIST1 ... concatenated together, with nested lists removed (flattened).

— procedure: intersperse

          (intersperse LIST X)
     

Returns a new list with X placed between each element.

— procedure: join

          (join LISTOFLISTS [LIST])
     

Concatenates the lists in LISTOFLISTS with LIST placed between each sublist. LIST defaults to the empty list.

     
     (join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)
     (join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t)

join could be implemented as follows:

     
     (define (join lstoflsts #!optional (lst '()))
       (apply append (intersperse lstoflists lst)) )

— procedure: shuffle

          (shuffle LIST)
     

Returns LIST with its elements sorted in a random order.

— procedure: tail?

          (tail? X LIST)
     

Returns true if X is one of the tails (cdr's) of LIST.

— procedure: call-with-input-string

          (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

          (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

          (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

          (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.

— procedure: fprintf
— procedure: printf
— procedure: sprintf
— procedure: format

          (fprintf PORT FORMATSTRING ARG ...)
          (printf FORMATSTRING ARG)
          (sprintf FORMATSTRING ARG ...)
          (format FORMATSTRING ARG ...)
     

Simple formatted output to a given port (fprintf), the value of (current-output-port) (printf) or a string (sprintf/format). The FORMATSTRING can contain any sequence of characters. The character `~' prefixes special formatting directives:

~%

write newline character

~N

the same as ~%

~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

(set! (hash-table-ref HT KEY) VAL)

(hash-table-set! HT KEY VAL)

— procedure: list->queue

          (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

          (make-queue)
     

Returns a newly created queue.

— procedure: queue?

          (queue? X)
     

Returns #t if X is a queue, or #f otherwise.

— procedure: queue->list

          (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-add! QUEUE X)
     

Adds X to the rear of QUEUE.

— procedure: queue-empty?

          (queue-empty? QUEUE)
     

Returns #t if QUEUE is empty, or #f otherwise.

— procedure: queue-first

          (queue-first QUEUE)
     

Returns the first element of QUEUE. If QUEUE is empty an error is signaled

— procedure: queue-last

          (queue-last QUEUE)
     

Returns the last element of QUEUE. If QUEUE is empty an error is signaled

— procedure: queue-remove!

          (queue-remove! QUEUE)
     

Removes and returns the first element of QUEUE. If QUEUE is empty an error is signaled

— procedure: merge
— procedure: merge!

          (merge LIST1 LIST2 LESS?)
          (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
— procedure: sort!

          (sort SEQUENCE LESS?)
          (sort! SEQUENCE LESS?)
     

Sort SEQUENCE, which should be a list or a vector. sort! is the destructive version of sort.

— procedure: sorted?

          (sorted? SEQUENCE LESS?)
     

Returns true if the list or vector SEQUENCE is already sorted.

— procedure: random

          (random N)
     

Returns an exact random integer from 0 to N-1.

— procedure: randomize

          (randomize [X])
     

Set random-number seed. If X is not supplied, the current time is used. On startup (when the extras unit is initialized), the random number generator is initialized with the current time.

— procedure: make-input-port

          (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 #!eof. 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 #!eof. 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

          (make-output-port WRITE CLOSE [FLUSH])
     

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 the port is closed and should be a procedure of no arguments. FLUSH (if provided) is called for flushing the output port.

— procedure: pretty-print
— procedure: pp

          (pretty-print EXP [PORT])
          (pp 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

          (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
     

Returns a list containing all toplevel expressions read from the file or port FILE-OR-PORT. If no argument is given, input is read from the port that is the current value of (current-input-port). After all expressions are read, and if the argument is a port, then the port will not be closed. The READER argument specifies the procedure used to read expressions from the given file or port and defaults to read. The reader procedure will be called with a single argument (an input port). If MAXCOUNT is given then only up to MAXCOUNT expressions will be read in.

— procedure: read-line
— procedure: write-line

          (read-line [PORT [LIMIT]])
          (write-line STRING [PORT])
     

Line-input and -output. PORT defaults to the value of (current-input-port) and (current-output-port), respectively. if the optional argument LIMIT is given and not #f, then read-line reads at most LIMIT characters per line.

— procedure: read-lines

          (read-lines [PORT [MAX]])
     

Read MAX or fewer lines from PORT. PORT defaults to the value of (current-input-port). PORT may optionally be a string naming a file.

— procedure: read-string
— procedure: write-string

          (read-string [NUM [PORT]])
          (write-string STRING [NUM [PORT]]
     

Read or write NUM characters from/to PORT, which defaults to the value of (current-input-port) or (current-output-port), respectively. If NUM is #f or not given, then all data up to the end-of-file is read, or, in the case of write-string the whole string is written. If no more input is available, read-string returns the empty string.

— procedure: read-token

          (read-token PREDICATE [PORT])
     

Reads characters from PORT (which defaults to the value of (current-input-port)) and calls the procedure PREDICATE with each character until PREDICATE returns false. Returns a string with the accumulated characters.

— procedure: with-error-output-to-port

          (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

          (with-input-from-port PORT THUNK)
     

Call procedure THUNK with the current input-port temporarily bound to PORT.

— procedure: with-output-to-port

          (with-output-to-port PORT THUNK)
     

Call procedure THUNK with the current output-port temporarily bound to PORT.

— procedure: conc

          (conc X ...)
     

Returns a string with the string-represenation of all arguments concatenated together. conc could be implemented as

     
     (define (conc . args)
       (apply string-append (map ->string args)) )

— procedure: ->string

          (->string X)
     

Returns a string-representation of X.

— procedure: string-chop

          (string-chop STRING LENGTH)
     

Returns a list of substrings taken by “chopping” STRING every LENGTH characters:

     
     (string-chop "one two three" 4)  ==>  ("one " "two " "thre" "e")

— procedure: string-compare3

          (string-compare3 STRING1 STRING2)
     

— procedure: string-compare3-ci

          (string-compare3-ci STRING1 STRING2)
     

Perform a three-way comparison between the STRING1 and STRING2, returning either -1 if STRING1 is lexicographically less than STRING2, 0 if it is equal, or 1 if it s greater. string-compare3-ci performs a case-insensitive comparison.

— procedure: string-intersperse

          (string-intersperse LIST [STRING])
     

Returns a string that contains all strings in LIST concatenated together. STRING is placed between each concatenated string and defaults to " ".

     
     (string-intersperse '("one" "two") "three")

is equivalent to

     
     (apply string-append (intersperse '("one" "two") "three"))

— procedure: string-split

          (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
     

Split string into substrings separated by the given delimiters. If no delimiters are specified, a string comprising the tab, newline and space characters 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-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: string-translate*

          (string-translate* STRING SMAP)
     

Substitutes elements of STRING according to SMAP. SMAP should be an association-list where each element of the list is a pair of the form (MATCH \. REPLACEMENT). Every occurrence of the string MATCH in STRING will be replaced by the string REPLACEMENT:

     
     (string-translate*
       "<h1>this is a \"string\"</h1>"
       '(("<" . "&lt:") (">" . "&gt;") ("\"" . "&quot;")) )
     
     ==>  "&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"

— procedure: substring=?
— procedure: substring-ci=?

          (substring=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
          (substring-ci=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
     

Returns #t if the strings STRING1 and STRING2 are equal, or #f otherwise. The comparison starts at the positions START1 and START2 (which default to 0), comparing LENGTH characters (which defaults to the minimum of the remaining length of both strings).

— procedure: substring-index
— procedure: substring-index-ci

          (substring-index WHICH WHERE [START])
          (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.

— procedure: constantly

          (constantly X ...)
     

Returns a procedure that always returns the values X ... regardless of the number and value of its arguments.

     
     (constantly X) <=> (lambda args X)

— procedure: complement

          (complement PROC)
     

Returns a procedure that returns the boolean inverse of PROC.

     
     (complement PROC) <=> (lambda (x) (not (PROC x)))

— procedure: compose

          (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: conjoin

          (conjoin PRED ...)
     

Returns a procedure that returns #t if its argument satisfies the predicates PRED ....

     
     ((conjoin odd? positive?) 33)   ==>  #t
     ((conjoin odd? positive?) -33)  ==>  #f

— procedure: disjoin

          (disjoin PRED ...)
     

Returns a procedure that returns #t if its argument satisfies any predicate PRED ....

     
     ((disjoin odd? positive?) 32)    ==>  #t
     ((disjoin odd? positive?) -32)   ==>  #f

— procedure: each

          (each PROC ...)
     

Returns a procedure that applies PROC ... to its arguments, and returns the result(s) of the last procedure application. For example

          (each pp eval)
     

is equivalent to

          (lambda args
            (apply pp args)
            (apply eval args) )
     

(each PROC) is equivalent to PROC and (each) is equivalent to noop.

— procedure: flip

          (flip PROC)
     

Returns a two-argument procedure that calls PROC with its arguments swapped:

     
     (flip PROC) <=> (lambda (x y) (PROC y x))

— procedure: identity

          (identity X)
     

Returns its sole argument X.

— procedure: project

          (project N)
     

Returns a procedure that returns its Nth argument (starting from 0).

— procedure: list-of

          (list-of PRED)
     

Returns a procedure of one argument that returns #t when applied to a list of elements that all satisfy the predicate procedure PRED, or #f otherwise.

     
     ((list-of even?) '(1 2 3))   ==> #f
     ((list-of number?) '(1 2 3)) ==> #t

— procedure: noop

          (noop X ...)
     

Ignores it's arguments, does nothing and returns an unspecified value.

— procedure: binary-search

          (binary-search SEQUENCE PROC)
     

Performs a binary search in SEQUENCE, which should be a sorted list or vector. PROC is called to compare items in the sequence, should accept a single argument and return an exact integer: zero if the searched value is equal to the current item, negative if the searched value is “less” than the current item, and positive otherwise.

— procedure: make-XXXvector

          (make-XXXvector SIZE [INIT NONGC FINALIZE])
     

Creates a SRFI-4 homogenous number vector of length SIZE. If INIT is given, it specifies the initial value for each slot in the vector. The optional arguments NONGC and FINALIZE define whether the vector should be allocated in a memory area not subject to garbage collection and whether the associated storage should be automatically freed (using finalization) when there are no references from Scheme variables and data. NONGC defaults to #f (the vector will be located in normal garbage collected memory) and FINALIZE defaults to #t. Note that the FINALIZE argument is only used when NONGC is true.

— procedure: u8vector->byte-vector
— procedure: s8vector->byte-vector
— procedure: u16vector->byte-vector
— procedure: s16vector->byte-vector
— procedure: u32vector->byte-vector
— procedure: s32vector->byte-vector
— procedure: f32vector->byte-vector
— procedure: f64vector->byte-vector

          (u8vector->byte-vector U8VECTOR)
          (s8vector->byte-vector S8VECTOR)
          (u16vector->byte-vector U16VECTOR)
          (s16vector->byte-vector S16VECTOR)
          (u32vector->byte-vector U32VECTOR)
          (s32vector->byte-vector S32VECTOR)
          (f32vector->byte-vector F32VECTOR)
          (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
— procedure: byte-vector->s8vector
— procedure: byte-vector->u16vector
— procedure: byte-vector->s16vector
— procedure: byte-vector->u32vector
— procedure: byte-vector->s32vector
— procedure: byte-vector->f32vector
— procedure: byte-vector->f64vector

          (byte-vector->u8vector BYTE-VECTOR)
          (byte-vector->s8vector BYTE-VECTOR)
          (byte-vector->u16vector BYTE-VECTOR)
          (byte-vector->s16vector BYTE-VECTOR)
          (byte-vector->u32vector BYTE-VECTOR)
          (byte-vector->s32vector BYTE-VECTOR)
          (byte-vector->f32vector BYTE-VECTOR)
          (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.

— procedure: subu8vector
— procedure: subu16vector
— procedure: subu32vector
— procedure: subs8vector
— procedure: subs16vector
— procedure: subs32vector
— procedure: subf32vector
— procedure: subf64vector

          (subu8vector U8VECTOR FROM TO)
          (subu16vector U16VECTOR FROM TO)
          (subu32vector U32VECTOR FROM TO)
          (subs8vector S8VECTOR FROM TO)
          (subs16vector S16VECTOR FROM TO)
          (subs32vector S32VECTOR FROM TO)
          (subf32vector F32VECTOR FROM TO)
          (subf64vector F64VECTOR FROM TO)
     

Creates a number vector of the same type as the argument vector with the elements at the positions FROM up to but not including TO.

SRFI-17 Setters for XXXvector-ref are defined.

(require-extension srfi-13)

(require-extension srfi-14)

— procedure: grep

          (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-search regex x)) lst) )

— procedure: glob->regexp

          (glob->regexp PATTERN)
     

Converts the file-pattern PATTERN into a regular expression.

     
     (glob->regexp "foo.*") ==> "foo\..*"

— procedure: regexp

          (regexp STRING [IGNORECASE [IGNORESPACE [UTF8]]])
     

Returns a precompiled regular expression object for string. The optional arguments IGNORECASE, IGNORESPACE and UTF8 specify whether the regular expression should be matched with case- or whitespace-differences ignored, or whether the string should be treated as containing UTF-8 encoded characters, respectively.

Notes:

• regex doesn't allow (?: ) cloisters (non-capturing groups) Currently this means if you use utf8 matching, individual "." matching will return extra submatches.
• pregexp doesn't allow a # comment w/o a trailing newline.

— procedure: regexp?

          (regexp? X)
     

Returns #t if X is a precompiled regular expression, or #f otherwise.

— procedure: string-match
— procedure: string-match-positions

          (string-match REGEXP STRING [START])
          (string-match-positions REGEXP STRING [START])
     

Matches the regular expression in REGEXP (a string or a precompiled regular expression) 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). Note that the exact string is matched. For searching a pattern inside a string, see below. Note also that string-match is implemented by calling string-search with the regular expression wrapped in ^ ... $.

— procedure: string-search
— procedure: string-search-positions

          (string-search REGEXP STRING [START [RANGE]])
          (string-search-positions REGEXP STRING [START [RANGE]])
     

Searches for the first match of the regular expression in REGEXP with STRING. The search can be limited to RANGE characters.

— procedure: string-split-fields

          (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.

          (define s "this is a string 1, 2, 3,")
          
          (string-split-fields "[^ ]+" s)
          
            => ("this" "is" "a" "string" "1," "2," "3,")
          
          (string-split-fields " " s #:infix)
          
            => ("this" "is" "a" "string" "1," "2," "3,")
          
          (string-split-fields "," s #:suffix))
          
            => ("this is a string 1" " 2" " 3")
     

— procedure: string-substitute

          (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)"

— procedure: string-substitute*

          (string-substitute* STRING SMAP)
     

Substitutes elements of STRING according to SMAP. SMAP should be an association-list where each element of the list is a pair of the form (MATCH . REPLACEMENT). Every occurrence of the regular expression MATCH in STRING will be replaced by the string REPLACEMENT

     
     (string-substitute* "<h1>Hello, world!</h1>"
                         '(("<[/A-Za-z0-9]+>" . ""))))
     
     ==>  "Hello, world!"

Note that back-references like \NUM are currently not supported.

— procedure: regexp-escape

          (regexp-escape STRING)
     

Escapes all special characters in STRING with \, so that the string can be embedded into a regular expression.

     
     (regexp-escape "^[0-9]+:.*$")   ==>  "\\^\\[0-9\\]\\+:.\n.\\*\\$"

— procedure: thread-deliver-signal!

          (thread-deliver-signal! THREAD X)
     

This will cause THREAD to signal the condition X once it is scheduled for execution. After signalling the condition, the thread continues with its normal execution.

— procedure: thread-quantum

          (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-set! THREAD QUANTUM)
     

Sets the quantum of THREAD to QUANTUM.

— procedure: change-directory

          (change-directory NAME)
     

Changes the current working directory to NAME.

— procedure: current-directory

          (current-directory [DIR])
     

Returns the name of the current working directory. If the optional argument DIR is given, then (current-directory DIR) is equivalent to (change-directory DIR).

— procedure: create-directory

          (create-directory NAME)
     

Creates a directory with the pathname NAME.

— procedure: delete-directory

          (delete-directory NAME)
     

Deletes the directory with the pathname NAME. The directory has to be empty.

— procedure: directory

          (directory [PATHNAME [SHOW-DOTFILES?]])
     

Returns a list with all files that are contained in the directory with the name PATHNAME (which defaults to the value of (current-directory)). If SHOW-DOTFILES? is given and not #f, then files beginning with “.” are not included in the directory listing.

— procedure: directory?

          (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

          (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).

— procedure: set-root-directory!

          (set-root-directory! STRING)
     

Sets the root directory for the current process to the path given in STRING (using the chroot function). If the current process has no root permissions, the operation will fail.

— procedure: call-with-input-pipe
— procedure: call-with-output-pipe

          (call-with-input-pipe CMDLINE PROC [MODE])
          (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
— procedure: close-output-pipe

          (close-input-pipe PORT)
          (close-output-pipe PORT)
     

Closes the pipe given in PORT and waits until the connected subprocess finishes. The exit-status code of the invoked process is returned.

— procedure: create-pipe

          (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

          (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

          (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
— procedure: with-output-to-pipe

          (with-input-from-pipe CMDLINE THUNK [MODE])
          (with-output-to-pipe CMDLINE THUNK [MODE])
     

Temporarily 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
     ) ) )

— procedure: create-fifo

          (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?

          (fifo? FILENAME)
     

Returns #t if the file with the name FILENAME names a FIFO.

— procedure: duplicate-fileno

          (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

          (file-close FILENO)
     

Closes the input/output file with the file-descriptor FILENO.

— procedure: file-open

          (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-mkstemp

          (file-mkstemp TEMPLATE-FILENAME)
     

Create a file based on the given TEMPLATE-FILENAME, in which the six last characters must be “XXXXXX”. These will be replaced with a string that makes the filename unique. The file descriptor of the created file and the generated filename is returned. See the mkstemp(3) manual page for details on how this function works. The template string given is not modified.

Example usage:

     
     (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
       (let ((temp-port (open-output-file* fd)))
         (format temp-port "This file is ~A.~%" temp-path)
         (close-output-port temp-port)))

— procedure: file-read

          (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 a list with two values: the buffer containing the data and the number of bytes read.

— procedure: file-select

          (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. READFDLIST and WRITEFDLIST may also by file-descriptors instead of lists. In this case the returned values are booleans indicating whether input/output is ready by #t or #f otherwise. You can also pass #f as READFDLIST or WRITEFDLIST argument, which is equivalent to ().

— procedure: file-write

          (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
— flag: open/fsync
— flag: open/binary
— flag: open/text

Flags for use with file-open.

— procedure: open-input-file*
— procedure: open-output-file*

          (open-input-file* FILENO [OPENMODE])
          (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->fileno PORT)
     

If PORT is a file- or tcp-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

— procedure: file-access-time
— procedure: file-change-time
— procedure: file-modification-time

          (file-access-time FILE)
          (file-change-time FILE)
          (file-modification-time FILE)
     

Returns time (in seconds) of the last acces, modification or change of FILE. FILE may be a filename or a file-descriptor. If the file does not exist, an error is signaled.

— procedure: file-stat

          (file-stat FILE [LINK])
     

Returns a 9-element vector with the following contents: inode-number, mode (as with file-permissions), number of hard links, uid of owner (as with file-owner), gid of owner, size (as with file-size) and access-, change- and modification-time (as with file-access-time, file-change-time and file-modification-time). If the optional argument LINK is given and not #f, then the file-statistics vector will be resolved for symbolic links (otherwise symbolic links are resolved).

— procedure: file-position

          (file-position FILE)
     

Returns the current file position of FILE, which should be a port or a file-descriptor.

— procedure: file-size

          (file-size FILENAME)
     

Returns the size of the file designated by FILE. FILE may be a filename or a file-descriptor. If the file does not exist, an error is signaled.

— procedure: regular-file?

          (regular-file? FILENAME)
     

Returns true, if FILENAME names a regular file (not a directory or symbolic link).

— procedure: file-truncate

          (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: set-file-position!

          (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.

Exceptions: (exn bounds), (exn i/o file)

— procedure: current-process-id

          (current-process-id)
     

Returns the process ID of the current process.

— procedure: parent-process-id

          (parent-process-id)
     

Returns the process ID of the parent of the current process.

— procedure: process-execute

          (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])
     

Creates a new child process and replaces the running process with it using the C library function execvp(3). If the optional argument ARGUMENT-LIST is given, then it should contain a list of strings which are passed as arguments to the subprocess. If the optional argument ENVIRONMENT-LIST is spplied, then the library function execve(2) is used, and the environment passed in ENVIRONMENT-LIST (which should be of the form ("<NAME>=<VALUE>" ...) is given to the invoked process. Note that execvp(3) respects the current setting of the PATH environment variable while execve(3) does not.

On native Windows, process-execute ignores the ENVIRONMENT-LIST arguments.

— procedure: process-fork

          (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

          (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 PATHNAME 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

          (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

          (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:

— procedure: process

          (process COMMANDLINE [ARGUMENTLIST [ENVIRONMENT]])
     

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 will be received as input in the sub-process and the process-id of the started sub-process. Blocking reads and writes to or from the ports returned by process only block the current thread, not other threads executing concurrently.

If ARGUMENTLIST is given, then the invocation of the subprocess is not done via the shell, but directly. The arguments are directly passed to process-execute (as is ENVIRONMENT). Not using the shell may be preferrable for security reasons.

On native Windows the ARGUMENTLIST and ENVIRONMENT arguments are ignored.

— procedure: sleep

          (sleep SECONDS)
     

Puts the process to sleep for SECONDS. Returns either 0 if the time has completely elapsed, or the number of remaining seconds, if a signal occurred.

— procedure: symbolic-link?

          (symbolic-link? FILENAME)
     

Returns true, if FILENAME names a symbolic link.

— procedure: create-symbolic-link

          (create-symbolic-link OLDNAME NEWNAME)
     

Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.

— procedure: read-symbolic-link

          (read-symbolic-link FILENAME)
     

Returns the filename to which the symbolic link FILENAME points.

— procedure: file-link

          (file-link OLDNAME NEWNAME)
     

Creates a hard link from OLDNAME to NEWNAME (both strings).

— procedure: file-owner

          (file-owner FILE)
     

Returns the user-id of FILE. FILE may be a filename or a file-descriptor.

— procedure: file-permissions

          (file-permissions FILE)
     

Returns the permission bits for FILE. You can test this value by performing bitwise operations on the result and the perm/... values. FILE may be a filename or a file-descriptor.

— procedure: file-read-access?
— procedure: file-write-access?
— procedure: file-execute-access?

          (file-read-access? FILENAME)
          (file-write-access? FILENAME)
          (file-execute-access? FILENAME)
     

These procedures return #t if the current user has read, write or execute permissions on the file named FILENAME.

— procedure: change-file-mode

          (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

          (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

          (current-user-id)
          (current-group-id)
          (current-effective-user-id)
          (current-effective-group-id)
     

Return the user- and group-ids of the current process.

— procedure: process-group-id

               (process-group-id PID)
          

Returns the process group ID of the process specified by PID.

— procedure: group-information

          (group-information GROUP)
     

If GROUP specifies a valid group-name or group-id, then this procedure returns a list of four values: the group-name, the encrypted group password, the group ID and a list of the names of all group members. If no group with the given name or ID exists, then #f is returned.

— procedure: get-groups

          (get-groups)
     

Returns a list with the supplementary group IDs of the current user.

— procedure: set-groups!

          (set-groups! GIDLIST)
     

Sets the supplementrary group IDs of the current user to the IDs given in the list GIDLIST.

Only the superuser may invoke this procedure.

— procedure: initialize-groups

          (initialize-groups USERNAME BASEGID)
     

Sets the supplementrary group IDs of the current user to the IDs from the user with name USERNAME (a string), including BASEGID.

Only the superuser may invoke this procedure.

— 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!

          (set-user-id! UID)
     

Sets the effective user id of the current process to UID, which should be a positive integer.

— procedure: set-group-id!

          (set-group-id! GID)
     

Sets the effective group id of the current process to GID, which should be a positive integer.

— procedure: set-process-group-id!

          (set-user-id! PID PGID)
     

Sets the process group ID of the process specifed by PID to PGID.

— procedure: user-information

          (user-information USER)
     

If USER specifes a valid username (as a string) or user ID, then the user database is consulted and a list of 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.

— procedure: create-session

          (create-session)
     

Creates a new session if the calling process is not a process group leader and returns the session ID.

— procedure: file-lock

          (file-lock PORT [START [LEN]])
     

Locks the file associated with PORT for reading or writing (according to whether 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-lock/blocking

          (file-lock/blocking PORT [START [LEN]])
     

Similar to file-lock, but if a lock is held on the file, the current process blocks (including all threads) until the lock is released.

— procedure: file-test-lock

          (file-test-lock PORT [START [LEN]])
     

Tests whether the file associated with PORT is locked for reading or writing (according to whether PORT is an input- or output-port) and returns either #f or the process-id of the locking process.

— procedure: file-unlock

          (file-unlock LOCK)
     

Unlocks the previously locked portion of a file given in LOCK.

— procedure: set-alarm!

          (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!

          (set-signal-handler! SIGNUM PROC)
     

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 argument PROC is #f then this signal will be ignored. Note that is is unspecified in which thread of execution the signal handler will be invoked.

— procedure: set-signal-mask!

          (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!.

— procedure: current-environment

          (current-environment)
     

Returns a association list of the environment variables and their current values.

— procedure: setenv

          (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

          (unsetenv VARIABLE)
     

Removes the definition of the environment variable VARIABLE from the environment of the current process. If the variable is not defined, nothing happens.

— pocedure: memory-mapped-file?

          (memory-mapped-file? X)
     

Returns #t, if X is an object representing a memory mapped file, or #f otherwise.

— procedure: map-file-to-memory

          (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: memory-mapped-file-pointer

          (memory-mapped-file-pointer MMAP)
     

Returns a machine pointer to the start of the memory region to which the file is mapped.

— procedure: unmap-file-from-memory

          (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.

— procedure: seconds->local-time

          (seconds->local-time SECONDS)
     

Breaks down the time value represented in SECONDS into a 10 element vector of the form #(seconds minutes hours mday month year wday yday dstflag timezone), in the following format:

• seconds: the number of seconds after the minute (0 - 59)
• minutes: the number of minutes after the hour (0 - 59)
• hours: the number of hours past midnight (0 - 23)
• mday: the day of the month (1 - 31)
• month: the number of months since january (0 - 11)
• year: the number of years since 1900
• wday: the number of days since Sunday (0 - 6)
• yday: the number of days since January 1 (0 - 365)
• dstflag: a flag that is true if Daylight Saving Time is in effect at the time described.
• timezone: the difference between UTC and the latest local standard time, in seconds west of UTC.

— procedure: local-time->seconds

          (local-time->seconds VECTOR)
     

Converts the ten-element vector VECTOR representing the time value relative to the current timezone into the number of seconds since the first of January, 1970 UTC.

— procedure: local-timezone-abbreviation

          (local-timezone-abbrevtiation)
     

Returns the abbreviation for the local timezone as a string.

— procedure: seconds->string

          (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->utc-time SECONDS)
     

Similar to seconds->local-time, but interpretes SECONDS as UTC time.

— procedure: utc-time->seconds

          (utc-time->seconds VECTOR)
     

Converts the ten-element vector VECTOR representing the UTC time value into the number of seconds since the first of January, 1970 UTC.

— procedure: time->string

          (time->string VECTOR)
     

Converts the broken down time represented in the 10 element vector VECTOR into a string of the form "Tue May 21 13:46:22 1991\n".

— procedure: _exit

          (_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
— error code: errno/exist
— error code: errno/wouldblock

These variables contain error codes as returned by errno.

— procedure: find-files

          (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
     

Recursively traverses the contents of DIRECTORY (which should be a string) and invokes the procedure ACTION for all files for which the procedure PREDICATE is true. PREDICATE may me a procedure of one argument or a regular-expression string. ACTION should be a procedure of two arguments: the currently encountered file and the result of the previous invocation of ACTION, or, if this is the first invocation, the value of IDENTITY. ACTION defaults to cons, IDENTITY defaults to (). LIMIT should a procedure of one argument that is called for each nested directory and which should return true, if that directory is to be traversed recursively. LIMIT may also be an exact integer that gives the maximum recursion depth. A depth of 0 means the files in the specified directory are traversed but not any nested directories. LIMIT may also be #f (the default), which is equivalent to (constantly #t).

Note that ACTION is called with the full pathname of each file, including the directory prefix.