This is chicken.info, produced by makeinfo version 4.8 from
chicken.texi.

   Copyright 2007-2008 Felix Winkelmann and the Chicken Team

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Chicken: (chicken).     A compiler that translates Scheme source files into C.
END-INFO-DIR-ENTRY


File: chicken.info,  Node: Top,  Next: The User's Manual,  Prev: (dir),  Up: (dir)

Chicken Scheme Reference Manual
*******************************

This is the top node.

* Menu:

* The User's Manual::
* Getting started::
* Basic mode of operation::
* Using the compiler::
* Using the interpreter::
* Supported language::
* Deviations from the standard::
* Extensions to the standard::
* Non-standard read syntax::
* Non-standard macros and special forms::
* Pattern matching::
* Declarations::
* Parameters::
* Unit library::
* Unit eval::
* Unit data-structures::
* Unit ports::
* Unit files::
* Unit extras::
* Unit srfi-1::
* Unit srfi-4::
* Unit srfi-13::
* Unit srfi-14::
* Unit srfi-69::
* Unit match::
* Unit regex::
* Unit srfi-18::
* Unit posix::
* Unit utils::
* Unit tcp::
* Unit lolevel::
* Interface to external functions and variables::
* Accessing external objects::
* Foreign type specifiers::
* Embedding::
* Callbacks::
* Locations::
* Other support procedures::
* C interface::
* chicken-setup::
* Data representation::
* Bugs and limitations::
* FAQ::
* Acknowledgements::
* Bibliography::


File: chicken.info,  Node: The User's Manual,  Next: Getting started,  Prev: Top,  Up: Top

1 The User's Manual
*******************

This is the user's manual for the Chicken Scheme compiler, version 3.4.0

*Note Getting started: Getting started.
     What is CHICKEN and how do I use it?

*Note Basic mode of operation: Basic mode of operation.
     Compiling Scheme files.

*Note Using the compiler: Using the compiler.
     Explains how to use CHICKEN to compile programs and execute them.

*Note Using the interpreter: Using the interpreter.
     Invocation and usage of `csi', the CHICKEN interpreter

*Note Supported language: Supported language.
     The language implemented by CHICKEN (deviations from the standard
     and extensions).

*Note Interface to external functions and variables: Interface to external functions and variables.
     Accessing C and C++ code and data.

*Note chicken-setup: chicken-setup.
     Packaging and installing extension libraries.

*Note Data representation: Data representation.
     How Scheme data is internally represented.

*Note Bugs and limitations: Bugs and limitations.
     Yes, there are some.

*Note FAQ: FAQ.
     A list of Frequently Asked Questions about CHICKEN (and their
     answers!).

*Note Acknowledgements: Acknowledgements.
     A list of some of the people that have contributed to make CHICKEN
     what it is.

*Note Bibliography: Bibliography.
     Links to documents that may be of interest.



File: chicken.info,  Node: Getting started,  Next: Basic mode of operation,  Prev: The User's Manual,  Up: Top

2 Getting started
*****************

* Menu:

* Getting started - Scheme::
* Getting started - Chicken::
* Getting started - Chicken repositories; websites; and community::
* Getting started - Installing Chicken::
* Getting started - Development environments::
* Getting started - The Read-Eval-Print loop::
* Getting started - The compiler::
* Getting started - Installing an egg::
* Getting started - Accessing C libraries::

   Chicken is a compiler that translates Scheme source files into C,
which in turn can be fed to a C compiler to generate a standalone
executable.  An interpreter is also available and can be used as a
scripting environment or for testing programs before compilation.

   This chapter is designed to get you started with Chicken
programming, describing what it is and what it will do for you, and
covering basic use of the system. With almost everything discussed
here, there is more to the story, which the remainder of the manual
reveals. Here, we only cover enough to get you started. Nonetheless,
someone who knows Scheme already should be able to use this chapter as
the basis for writing and running small Chicken programs.


File: chicken.info,  Node: Getting started - Scheme,  Next: Getting started - Chicken,  Up: Getting started

2.1 Scheme
==========

Scheme is a member of the Lisp family of languages, of which Common
Lisp and Emacs Lisp are the other two widely-known members. As with
Lisp dialects, Scheme features

   * a wide variety of programming paradigms, including imperative,
     functional, and object-oriented

   * a very simple syntax, based upon nested parenthesization

   * the ability to extend the language in meaningful and useful ways

   In contrast to Common Lisp, Scheme is very minimal, and tries to
include only those features absolutely necessary in programming. In
contrast to Emacs Lisp, Scheme is not anchored into any one program
(Emacs), and has a somewhat more modern language design.

   Scheme is defined in a document called _The Revised^5 Report on the
Algorithmic Language Scheme_, or _R5RS_ for short. (Yes, it really has
been revised five times, so an expanded version of its name would be
_The Revised Revised Revised Revised Revised Report_.)  A newer report,
_R6RS_, was  released in 2007, but this report has attracted
considerable controversy, and not all Scheme implementations will be
made compliant with it. Chicken essentially complies with R5RS.

   Even though Scheme is consciously minimalist, it is recognized that
a language must be more than a minimal core in order to be useful.
Accordingly, the Scheme community uses a process known as `Scheme
Requests For Implementation' (SRFI, pronounced `SUR-fee') to define new
language features. A typical Scheme system therefore complies with one
of the Scheme reports plus some or all of the accepted SRFIs.

   A good starting point for Scheme knowledge is
http://www.schemers.org (http://www.schemers.org). There you will find
the defining reports, FAQs, lists of useful books and other resources,
and the SRFIs.

   The Chicken community is at present developing tutorials for
programmers who are new to Scheme but experienced with Python, Ruby, or
other languages. These can be found on the Chicken wiki.


File: chicken.info,  Node: Getting started - Chicken,  Next: Getting started - Chicken repositories; websites; and community,  Prev: Getting started - Scheme,  Up: Getting started

2.2 Chicken
===========

Chicken is an implementation of Scheme that has many advantages.

   <blockquote> Chicken Scheme combines an optimising compiler with a
reasonably fast interpreter.  It supports almost all of R5RS and the
important SRFIs. The compiler generates portable C code that supports
tail recursion, first-class continuations, and lightweight threads, and
the interface to and from C libraries is flexible, efficient, and easy
to use.  There are hundreds of contributed Chicken libraries that make
the programmer's task easier.  The interpreter allows interactive use,
fast prototyping, debugging, and scripting.  The active and helpful
Chicken community fixes bugs and provides support.  Extensive
documentation is supplied. </blockquote>

   Chicken was developed by Felix L. Winkelmann over the period from
2000 through 2007. In early 2008, Felix asked the community to take
over the responsibility of developing and maintaining the system,
though he still takes a strong interest in it, and participates
actively.

   Chicken includes

   * a Scheme interpreter that supports almost all of  R5RS Scheme,
     with   only a few relatively minor omissions, and with many
     extensions

   * a compatible compiler whose target is C, thus making porting to
     new   machines and architectures relatively straightforward
        * the C support allows Scheme code to include `embedded' C
          code,   thus making it relatively easy to invoke host OS or
          library   functions


   * a framework for language extensions, library modules that broaden
     the functionality of the system

   This package is distributed under the BSD license and as such is
free to use and modify.

   Scheme cognoscenti will appreciate the method of compilation and the
design of the runtime-system, which follow closely Henry Baker's Part
II: Cheney on the M.T.A. paper and expose a number of interesting
properties.

   * Consing (creation of data on the heap) is relatively inexpensive,
     because a generational garbage collection scheme is used, in
     which   short-lived data structures are reclaimed extremely
     quickly.

   * Moreover, `call-with-current-continuation' is practically for free
      and Chicken does not suffer under any performance penalties if
     first-class continuations are used in complex ways.

   The generated C code is fully tail-recursive.

   Some of the features supported by Chicken:

   * SRFIs 0, 1, 2, 4, 6-19, 23, 25-31, 37-40, 42, 43, 45, 47, 55, 57,
     60-63, 66, 69, 72, 78, 85 and 95.

   * Lightweight threads based on first-class continuations

   * Pattern matching with Andrew Wright's `match' package

   * Record structures

   * Extended comment- and string-literal syntaxes

   * Libraries for regular expressions, string handling

   * UNIX system calls and extended data structures

   * Create interpreted or compiled shell scripts written in Scheme for
      UNIX or Windows

   * Compiled C files can be easily distributed

   * Allows the creation of fully self-contained statically linked
     executables

   * On systems that support it, compiled code can be loaded dynamically

   Chicken has been used in many environments ranging from embedded
systems through desktop machines to large-scale server deployments.
The number of language extensions, or eggs, will soon reach 400,
including

   * extended language features

   * development tools, such as documentation generators, debugging,
     and   automated testing libraries

   * interfaces to other languages such as Java, Python, and Objective-C

   * interfaces to database systems, GUIs, and other large-scale
     libraries,

   * network applications, such as servers and clients for ftp,
     smtp/pop3, irc, and http

   * web servers and related tools, including URL parsing, HTML
     generation, AJAX, and HTTP session management

   * data formats, including XML, JSON, and Unicode support

   Chicken is supported by SWIG (Simplified Wrapper and Interface
Generator), a tool that produces quick-and-dirty interface modules for
C libraries (http://www.swig.org (http://www.swig.org)).

   This chapter provides you with an overview of the entire system,
with enough information to get started writing and running small Scheme
programs. Subsequent chapters cover

   * *Note Basic mode of operation: Basic mode of operation.: Compiling
     Scheme files.

   * *Note Using the compiler: Using the compiler.: Explains how to use
     Chicken to compile   programs and execute them.

   * *Note Using the interpreter: Using the interpreter.: Invocation
     and usage of `csi', the   Chicken interpreter

   * *Note Supported language: Supported language.: The language
     implemented by Chicken   (deviations from the standard and
     extensions).

   * *Note Interface to external functions and variables: Interface to
     external functions and variables.: Accessing C and   C++ code and
     data.

   * *Note chicken-setup: chicken-setup.: Packaging and installing
     extension libraries.

   * *Note Data representation: Data representation.: How Scheme data
     is internally represented.

   * *Note Bugs and limitations: Bugs and limitations.: Yes, there are
     some.

   * *Note FAQ: FAQ.: A list of Frequently Asked Questions about
     Chicken (and   their answers!).

   * *Note Acknowledgements: Acknowledgements.: A list of some of the
     people that have   contributed to make Chicken what it is.

   * *Note Bibliography: Bibliography.: Links to documents that may be
     of interest.



File: chicken.info,  Node: Getting started - Chicken repositories; websites; and community,  Next: Getting started - Installing Chicken,  Prev: Getting started - Chicken,  Up: Getting started

2.3 Chicken repositories, websites, and community
=================================================

At present, the URLs for Chicken information and download are somewhat
confusing. It is envisaged that everything will eventually be
accessible via the  domain `chicken-scheme.org', but this hasn't been
completely done.

   At present, the master Chicken website is
http://www.call-with-current-continuation.org
(http://www.call-with-current-continuation.org). Here you can find
basic information about Chicken, downloads, and pointers to other key
resources.

   The Chicken wiki (http://chicken.wiki.br (http://chicken.wiki.br))
contains the most current version of the User's manual, along with
various tutorials and other useful documents. The list of eggs is at
http://chicken.wiki.br/Eggs%20Unlimited%203
(http://chicken.wiki.br/Eggs%20Unlimited%203).

   A very useful search facility for questions about Chicken is found
at http://www.callcc.org (http://www.callcc.org). The Chicken issue
tracker is at http://trac.callcc.org (http://trac.callcc.org).

   The Chicken community has two major mailing lists. If you are a
Chicken user, `Chicken-Users'
(http://lists.nongnu.org/mailman/listinfo/chicken-users
(http://lists.nongnu.org/mailman/listinfo/chicken-users)) will be of
interest. The crew working on the Chicken system itself uses the very
low-volume `Chicken-Hackers' list
(http://lists.nongnu.org/mailman/listinfo/chicken-hackers
(http://lists.nongnu.org/mailman/listinfo/chicken-hackers)) for
communication.


File: chicken.info,  Node: Getting started - Installing Chicken,  Next: Getting started - Development environments,  Prev: Getting started - Chicken repositories; websites; and community,  Up: Getting started

2.4 Installing Chicken
======================

Chicken is available in binary form for Windows and Linux/x86 systems,
and in source form for all other platforms. Refer to the `README' file
in the distribution for instructions on installing it on your system.

   Because it compiles to C, Chicken requires that a C compiler be
installed on your system. (If you're not writing embedded C code, you
can pretty much ignore the C compiler once you have installed it.)

   * On a Linux system, the GNU Compiler Collection (`gcc') should be
     installed as part of the basic operating system, or should be
     available through the package management system (e.g., APT,
     Synaptic, RPM, or Yum, depending upon your Linux distribution).

   * On Macintosh OS X, you will need the XCode tools, which are
     shipped   on the OS X DVD with recent versions of the operating
     system.

   * On Windows, you have three choices.
        * Cygwin (http://sources.redhat.com/cygwin
          (http://sources.redhat.com/cygwin)) provides a relatively
          full-featured Unix environment for Windows.  Chicken works
          substantially the same in Cygwin and Unix.

        * The GNU Compiler Collection has been ported to Windows, in
          the   MinGW system (http://mingw.sourceforge.net
          (http://mingw.sourceforge.net)). Unlike Cygwin,   executables
          produced with MinGW do not need the Cygwin DLLs in order   to
          run.   MSys is a companion package to MinGW; it provides a
          minimum   Unix-style development/build environment, again
          ported from free   software.
             * You can build Chicken either with MinGW alone or with
               MinGW plus    MSys. Both approaches produce a Chicken
               built against the mingw headers    and import libraries.
                The only difference is the environment where you
               actually run make.   `Makefile.mingw' is can be used in
               `cmd.exe' with the version of make   that comes with
               mingw.  `Makefile.mingw-msys'    uses unix commands such
               as `cp' and `rm'.  The end product is the   same.


        * Microsoft Visual Studio will soon be supported, including the
           Express edition, which is a non-free but no-cost compiler
          suite   available from Microsoft
          (http://www.microsoft.com/express/vc
          (http://www.microsoft.com/express/vc)). Chicken supports
          command-line building using the command-line C/C++ compiler.
             * Visual   Studio users will want to install the Unix
               Utilities, available at
               http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip
               (http://www.call-with-current-continuation.org/tarballs/UnxUtils.zip),
                in order to get suitable versions of `make', `tar',
               `gzip', and   similar commands.



   Refer to the `README' file for the version you're installing for
more information on the installation process.


File: chicken.info,  Node: Getting started - Development environments,  Next: Getting started - The Read-Eval-Print loop,  Prev: Getting started - Installing Chicken,  Up: Getting started

2.5 Development environments
============================

The simplest development environment is a text editor and terminal
window (Windows: Command Prompt, OSX: Terminal, Linux/Unix: xterm) for
using the interpreter and/or calling the compiler. If you install the
`readline' egg (http://chicken.wiki.br/readline), you have all the
benefits of command history in the interpreter, Emacs or vi-compatible
line editing, and customization.

   You will need a text editor that knows Scheme; it's just too painful
with editors that don't do parenthesis matching and proper indentation.
Some editors allow you to execute Scheme code directly in the editor.
This makes programming very interactive: you can type in a function and
then try it right away. This feature is very highly recommended.

   As programmers have very specific tastes about editors, the editors
listed here are shown in alphabetic order. We aren't about to tell you
which editor to use, and there may be editors not shown here that might
satisfy your needs. We would be very interested in reports of other
editors that have been used with Chicken, especially those that support
interactive evaluation of forms during editing. Pointers to these (and
to any editor customization files appropriate) should be put on the
Chicken wiki, and will likely be added to future editions of this
manual. (We have had a request for editors that support proportional
fonts, in particular.)

   * Emacs (http://www.gnu.org/software/emacs
     (http://www.gnu.org/software/emacs)) is an extensible,
     customizable, self-documenting editor available for Linux/Unix,
     Macintosh, and Windows systems; CHICKEN provides Emacs support out
     of the box, with the `hen.el' Emacs Lisp file. Consult the `Emacs
     Guide for Chicken Users' (which will be available on the Chicken
     Wiki soon) for information on setting up and using Emacs with
     Chicken.

   * Epsilon (http://www.lugaru.com (http://www.lugaru.com)) is a
     commercial (proprietary) text editor whose design was inspired by
     Emacs. Although Scheme support isn't provided, a Lisp mode is
     available on Lugaru's FTP site, and could with some work be made
     to duplicate the Emacs support.

   * SciTE (http://scintilla.sourceforge.net/SciTE.html
     (http://scintilla.sourceforge.net/SciTE.html)),  unlike Emacs or
     Vim, follows typical graphical UI design conventions and
     control-key mappings, and for simple tasks is as familiar and easy
     to use as Notepad, KEdit, TeachText etc.  However it has many
     programming features such as multiple open files, syntax
     highlighting for a large number of languages (including Lisps),
     matching of brackets, ability to fold sections of code based on
     the matched brackets, column selections, comment/uncomment, and
     the ability to run commands in the same directory as the current
     file (such as make, grep, etc.)  SciTE is written with the GTK
     toolkit and is portable to any GTK platform, including Windows,
     Linux and MacOS.  It uses the Scintilla text-editing component,
     which lends itself well to embedding within other IDEs and
     graphical toolkits. It does not have any other Scheme-specific
     features, but being open-source and modular, features like
     auto-formatting of S-expressions could be added.  The syntax
     highlighting can be configured to use different fonts for
     different types of syntax, including proportional fonts.

   * Vim (http://www.vim.org (http://www.vim.org)) is a highly
     configurable text editor built to enable efficient and fast text
     editing. It is an improved version of the vi editor distributed
     with most UNIX systems. Vim comes with generic Lisp (and therefore
     Scheme) editing capabilities out of the box. A few tips on using
     Vim with Chicken can be found at
     http://cybertiggyr.com/gene/15-vim/
     (http://cybertiggyr.com/gene/15-vim/).

   In the rest of this chapter, we'll assume that you are using an
editor of your choice and a regular terminal window for executing your
Chicken code.


File: chicken.info,  Node: Getting started - The Read-Eval-Print loop,  Next: Getting started - The compiler,  Prev: Getting started - Development environments,  Up: Getting started

2.6 The Read-Eval-Print loop
============================

* Menu:

* Getting started - The Read-Eval-Print loop - Scripts::

   To invoke the Chicken interpreter, you use the `csi' command.


$ csi
CHICKEN
(c)2008 The Chicken Team
(c)2000-2007 Felix L. Winkelmann
Version 3.1.2 - macosx-unix-gnu-x86	[ manyargs dload ptables applyhook ]
SVN rev. 10185	compiled 2008-03-27 on argyre.local (Darwin)
#;1>
 This brings up a brief banner, and then the prompt. You can use this
pretty much like any other Scheme system, e.g.,


#;1> (define (twice f) (lambda (x) (f (f x))))
#;2> ((twice (lambda (n) (* n 10))) 3)
300
 Suppose  we have already created a file `fact.scm' containing a
function definition.


(define (fact n)
  (if (= n 0)
      1
      (* n (fact (- n 1)))))
 We can now load this file and try out the function.


#;3> (load "fact.scm")
; loading fact.scm ...
#;4> (fact 3)
6
 The read-eval-print loop (REPL) is the component of the Scheme system
that _reads_ a Scheme expression, _eval_uates it, and _prints_ out the
result. The REPL's prompt can be customized (see the `Using the
Interpreter' (http:Using%20the%20interpreter)) but the default prompt,
showing the number of the form, is quite convenient.

   The REPL also supports debugging commands:  input lines beginning
with a `,' (comma) are treated as special commands. (See the *Note full
list: Using the interpreter - Toplevel commands.) We can trace `fact'
to see how it works.


#;5> ,tr fact
#;5> (fact 3)
|(fact 3)
| (fact 2)
|  (fact 1)
|   (fact 0)
|   fact -> 1
|  fact -> 1
| fact -> 2
|fact -> 6
6
 The command number didn't increment, because the `tr' command isn't
actually a Scheme _form_.


File: chicken.info,  Node: Getting started - The Read-Eval-Print loop - Scripts,  Up: Getting started - The Read-Eval-Print loop

2.6.1 Scripts
-------------

You can use the interpreter to run a Scheme program from the command
line. Here we create a program that does a quick search-and-replace on
an input file; the arguments are a regular expression and a replacement
string.


$ cat quickrep.dat
xyzabcghi
abxawxcgh
foonly
$ csi -ss quickrep.scm <quickrep.dat 'a.*c' A
xyzAghi
Agh
foonly
 The `-ss' option sets several options that work smoothly together to
execute a script. You can make the command directly executable from the
shell by inserting a `*Note shebang line: Using the interpreter -
Writing Scheme scripts.' at the beginning of the program.

   `regex', the regular expression library, is one of the libraries
included with Chicken.


(use regex)
(define (process-line line re rplc)
  (string-substitute re rplc line 'all))
(define (quickrep re rplc)
  (let ((line (read-line)))
    (if (not (eof-object? line))
        (begin
          (display (process-line line re rplc))
          (newline)
          (quickrep re rplc)))))
;;; Does a lousy job of error checking!
(define (main args)
  (quickrep (regexp (car args)) (cadr args)))
 The `-ss' option arranges to call a procedure named `main', with the
command line arguments, packed in a list, as its arguments. (There are
a number of ways this program could be made more idiomatic Chicken
Scheme, see the rest of the manual for details.)


File: chicken.info,  Node: Getting started - The compiler,  Next: Getting started - Installing an egg,  Prev: Getting started - The Read-Eval-Print loop,  Up: Getting started

2.7 The compiler
================

There are several reasons you might want to compile your code.

   * Compiled code executes substantially faster than interpreted
     code.

   * You might want to deploy an application onto machines where the
     users aren't expected to have Chicken installed: compiled
     applications can be self-contained.

   The Chicken compiler is provided as the command `chicken', but in
almost all cases, you will want to use the `csc' command instead. `csc'
is a convenient driver that automates compiling Scheme programs into C,
compiling C code into object code, and linking the results into an
executable file. (Note: in a Windows environment with Visual Studio,
you may find that `csc' refers to Microsoft's C# compiler. There are a
number of ways of sorting this out, of which the simplest is to rename
one of the two tools, and/or to  organize your `PATH' according to the
task at hand.)

   Compiled code can be intermixed with interpreted code on systems
that support dynamic loading, which includes modern versions of *BSD,
Linux, Mac OS X, Solaris, and Windows.

   We can compile our factorial function, producing a file named
`fact.so' (`shared object' in Linux-ese, the same file type is used in
OS X and Windows, rather than `dylib' or `dll', respectively).


chicken$ csc -dynamic fact.scm
chicken$ csi -quiet
#;1> (load "fact.so")
; loading fact.so ...
#;2> (fact 6)
720
 On any system, we can just compile a program directly into an
executable. Here's a program that tells you whether its argument is a
palindrome.


(define (palindrome? x)
  (define (check left right)
    (if (>= left right)
        #t
        (and (char=? (string-ref x left) (string-ref x right))
             (check (add1 left) (sub1 right)))))
  (check 0 (sub1 (string-length x))))
(let ((arg (car (command-line-arguments))))
  (display
   (string-append arg
                  (if (palindrome? arg)
                      " is a palindrome\n"
                      " isn't a palindrome\n"))))

 We can compile this program using `csc', creating an executable named
`palindrome'.


$ csc -o palindrome palindrome.scm
$ ./palindrome level
level is a palindrome
$ ./palindrome liver
liver isn't a palindrome
 Chicken supports separate compilation, using some extensions to
Scheme. Let's divide our palindrome program into a library module
(`pal-proc.scm') and a client module (`pal-user.scm').

   Here's the external library. We `declare' that `pal-proc' is a
`unit', which is the basis of separately-compiled modules in Chicken.
(Units deal with separate compilation, but don't involve separated
namespaces; namespaced module systems are available as eggs.)


;;; Library pal-proc.scm
(declare (unit pal-proc))
(define (palindrome? x)
  (define (check left right)
    (if (>= left right)
        #t
        (and (char=? (string-ref x left) (string-ref x right))
             (check (add1 left) (sub1 right)))))
  (check 0 (sub1 (string-length x))))
 Next we have some  client code that `uses' this separately-compiled
module.


;;; Client pal-user.scm
(declare (uses pal-proc))
(let ((arg (car (command-line-arguments))))
  (display
   (string-append arg
                  (if (palindrome? arg)
                      " is a palindrome\n"
                      " isn't a palindrome\n"))))
 Now we can compile and link everything together. (We show the compile
and link operations separately, but they can of course be combined into
one command.)


$ csc -c pal-proc.scm
$ csc -c pal-user.scm
$ csc -o pal-separate pal-proc.o pal-user.o
$ ./pal-separate level
level is a palindrome


File: chicken.info,  Node: Getting started - Installing an egg,  Next: Getting started - Accessing C libraries,  Prev: Getting started - The compiler,  Up: Getting started

2.8 Installing an egg
=====================

Installing eggs is quite straightforward on systems that support
dynamic loading (again, that would include *BSD, Linux, Mac OS X,
Solaris, and Windows).  The command `chicken-setup' will fetch an egg
from the master Chicken repository, and install it on your local system.

   In this example, we install the `uri' egg, for parsing Uniform
Resource Identifiers. The installation produces a lot of output, which
we have edited for space reasons.


$ chicken-setup uri

The extension uri does not exist.
Do you want to download it ? (yes/no/abort) [yes] yes
downloading uri.egg from (www.call-with-current-continuation.org eggs/3 80)
  gzip -d -c ../uri.egg | tar xf -
.  /Users/vmanis/local/bin/csc -feature compiling-extension
     -s -O2 -d1 uri.scm -o uri.so -check-imports -emit-exports uri.exports
... (lots of stuff elided)
.  rm -fr /Users/vmanis/project/chicken/uri.egg
 First, `chicken-setup' asks us if we want to download the egg. It then
uncompresses the egg, compiles the code, and installs the egg in the
local Chicken repository.

   Now we can use our new egg.


#;1> (use uri)
; loading /Users/vmanis/local/lib/chicken/3/uri.so ...
; loading /Users/vmanis/local/lib/chicken/3/coerce-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/misc-extn-list-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/synch-support.so ...
; loading /Users/vmanis/local/lib/chicken/3/lookup-table.so ...
; loading /Users/vmanis/local/lib/chicken/3/misc-extn-control-support.so ...
#;2> (uri-host (uri "uref{http://www.foobar.org/blah, http://www.foobar.org/blah}"))
"www.foobar.org"


File: chicken.info,  Node: Getting started - Accessing C libraries,  Prev: Getting started - Installing an egg,  Up: Getting started

2.9 Accessing C libraries
=========================

Because Chicken compiles to C, and because a foreign function interface
is built into the compiler, interfacing to a C library is quite
straightforward. This means that nearly any facility available on the
host system is accessible from Chicken, with more or less work.

   Let's create a simple C library, to demonstrate how this works. Here
we have a function that will compute and return the nth Fibonacci
number. (This isn't a particularly good use of C here, because we could
write this function just as easily in Scheme, but a real example would
take far too much space here.)


int fib(int n) {
  int prev = 0, curr = 1;
  int next;
  int i;
  for (i = 0; i < n; i++) {
    next = prev + curr;
    prev = curr;
    curr = next;
  }
  return curr;
}
 Now we can call this function from Chicken.


#>
  extern fib(int n);
<#
(define xfib (foreign-lambda int "fib" int))
(do ((i 0 (+ i 1))) ((> i 10))
  (printf "~A " (xfib i)))
(newline)
 The syntax `#>...<#' allows you to include literal C (typically
external declarations) in your Chicken code. We access `fib' by
defining a `foreign-lambda' for it, in this case saying that the
function takes one integer argument (the `int' after the function
name), and that it returns an integer result (the `int' before.) Now we
can invoke `xfib' as though it were an ordinary Scheme function.


$ gcc -c fib.c
$ csc -o fib-user fib.o fib-user.scm
$ ./fib-user
0 1 1 2 3 5 8 13 21 34 55
 Those who are interfacing to substantial C libraries should consider
using the  easyffi egg, or SWIG.

   Back to *Note The User's Manual: The User's Manual. Next: *Note
Basic mode of operation: Basic mode of operation.


File: chicken.info,  Node: Basic mode of operation,  Next: Using the compiler,  Prev: Getting started,  Up: Top

3 Basic mode of operation
*************************

The compiler translates Scheme source code into fairly portable C that
can be compiled and linked with most available C compilers. CHICKEN
supports the generation of executables and libraries, linked either
statically or dynamically. Compiled Scheme code can be loaded
dynamically, or can be embedded in applications written in other
languages. Separate compilation of modules is fully supported.

   The most portable way of creating separately linkable entities is
supported by so-called _unit_s.  A unit is a single compiled object
module that contains a number of toplevel expressions that are executed
either when the unit is the _main_ unit or if the unit is _used_.  To
use a unit, the unit has to be _declare_ed as used, like this:

     (declare (uses UNITNAME))
   The toplevel expressions of used units are executed in the order in
which the units appear in the `uses' declaration. Units may be used
multiple times and `uses' declarations may be circular (the unit is
initialized at most once).  To compile a file as a unit, add a `unit'
declaration:

     (declare (unit UNITNAME))
   When compiling different object modules, make sure to have one main
unit. This unit is called initially and initializes all used units
before executing its toplevel expressions. The main-unit has no `unit'
declaration.

   Another method of using definitions in separate source files is to
_include_ them. This simply inserts the code in a given file into the
current file:

     (include *"FILENAME"*)
   Macro definitions are only available when processed by `include' or
`require-for-syntax'. Macro definitions in separate units are not
available, since they are defined at compile time, i.e the time when
that other unit was compiled (macros can optionally be available at
runtime, see `define-macro' in *Note Substitution forms and macros:
Non-standard macros and special forms.).

   On platforms that support dynamic loading of compiled code (
Windows, most ELF based systems like Linux or BSD, MacOS X, and others)
code can be compiled into a shared object `.dll', `.so', `.dylib') and
loaded  dynamically into a running application.

   Previous: *Note Getting started: Getting started. Next: *Note Using
the compiler: Using the compiler.


File: chicken.info,  Node: Using the compiler,  Next: Using the interpreter,  Prev: Basic mode of operation,  Up: Top

4 Using the compiler
********************

* Menu:

* Using the compiler - Compiler command line format::
* Using the compiler - Runtime options::
* Using the compiler - Examples::
* Using the compiler - Extending the compiler::
* Using the compiler - Distributing compiled C files::

   The interface to `chicken' is intentionally simple.  System
dependent makefiles, shell-scripts or batch-files should perform any
necessary steps before and after invocation of `chicken'. A program
named `csc' provides a much simpler interface to the Scheme- and
C-compilers and linker. Enter


csc -help
 on the command line for more information.


File: chicken.info,  Node: Using the compiler - Compiler command line format,  Next: Using the compiler - Runtime options,  Up: Using the compiler

4.1 Compiler command line format
================================


chicken FILENAME {OPTION}
 `FILENAME' is the complete pathname of the source file that is to be
translated into C. A filename argument of `-' specifies that the source
text should be read from standard input. Note that the filename has to
be the first argument to `chicken'.

Possible options are:

-analyze-only
     Stop compilation after first analysis pass.

-benchmark-mode
     Equivalent to `-no-trace -no-lambda-info -optimize-level 3'
     `-fixnum-arithmetic -disable-interrupts -block -lambda-lift'.

-block
     Enable block-compilation. When this option is specified, the
     compiler assumes that global variables are not modified outside
     this compilation-unit.  Specifically, toplevel bindings are not
     seen by `eval' and unused toplevel bindings are removed.

-case-insensitive
     Enables the reader to read symbols case insensitive. The default
     is to read case sensitive (in violation of R5RS).  This option
     registers the `case-insensitive' feature identifier.

-check-imports
     Search for references to undefined global variables. For each
     library unit accessed via `(declare (uses ...))', the compiler
     will search a file named `UNITNAME.exports' in the current include
     path and load its contents into the _import-table_ (if found).
     Also, export-information for extensions (accessed through
     `(require-extension ...)') will be searched and stored in the
     import-table. If a required extension does not provide explicit
     export-information a `.exports' file is searched (as with used
     units). After the analysis phase of the compiler, referenced
     toplevel variables for which no assignment was found will generate
     a warning. Also, re-assignments of imported variables will trigger
     a warning.

-check-syntax
     Aborts compilation process after macro-expansion and syntax checks.

-debug MODES
     Enables one or more compiler debugging modes. `MODES' is a string
     of characters that select debugging information about the compiler
     that will be printed to standard output.



    t          show time needed for compilation
    b          show breakdown of time needed for each compiler pass
    o          show performed optimizations
    r          show invocation parameters
    s          show program-size information and other statistics
    a          show node-matching during simplification
    p          show execution of compiler sub-passes
    l          show lambda-lifting information
    m          show GC statistics during compilation
    n          print the line-number database
    c          print every expression before macro-expansion
    u          lists all unassigned global variable references
    x          display information about experimental features
    D          when printing nodes, use node-tree output
    N          show the real-name mapping table
    U          show expressions after the secondary user pass
    0          show database before lambda-lifting pass
    L          show expressions after lambda-lifting
    M          show unit-information and syntax-/runtime-requirements
    1          show source expressions
    2          show canonicalized expressions
    3          show expressions converted into CPS
    4          show database after each analysis pass
    5          show expressions after each optimization pass
    6          show expressions after each inlining pass
    7          show expressions after complete optimization
    8          show database after final analysis
    9          show expressions after closure conversion
-debug-level LEVEL
     Selects amount of debug-information. `LEVEL' should be an integer.



    -debug-level 0             is equivalent to -no-trace -no-lambda-info
    -debug-level 1             is equivalent to -no-trace
    -debug-level 2             does nothing (the default)
-disable-interrupts
     Equivalent to the `(disable-interrupts)' declaration. No
     interrupt-checks are generated for compiled programs.

-disable-compiler-macros
     disable expansion of compiler macros.

-disable-stack-overflow-checks
     Disables detection of stack overflows. This is equivalent to
     running the compiled executable with the `-:o' runtime option.

-disable-warning CLASS : Disables specific class of warnings, may be given multiple times. The following classes are defined


    usage              warnings related to command-line arguments
    type               warnings related to type-conversion
    ext                warnings related to extension libraries
    var                warnings related to variable- and syntax-definitions and use
    const              warnings related to constant-definitions
    syntax             syntax-related warnings
    redef              warnings about redefinitions of standard- or extended-bindings
    call               warnings related to known procedure calls
    ffi                warnings related to the foreign function interface
-dynamic
     This option should be used when compiling files intended to be
     loaded dynamically into a running Scheme program.

-epilogue FILENAME
     Includes the file named `FILENAME' at the end of the compiled
     source file. The include-path is not searched. This option may be
     given multiple times.

-emit-exports FILENAME
     Write exported toplevel variables to `FILENAME'.

-emit-external-prototypes-first
     Emit prototypes for callbacks defined with `define-external'
     before any other foreign declarations. This is sometimes useful,
     when C/C++ code embedded into the a Scheme program has to access
     the callbacks. By default the prototypes are emitted after foreign
     declarations.

-explicit-use
     Disables automatic use of the units `library, eval' and `extras'.
     Use this option if compiling a library unit instead of an
     application unit.

-extend FILENAME
     Loads a Scheme source file or compiled Scheme program (on systems
     that support it) before compilation commences. This feature can be
     used to extend the compiler.  This option may be given multiple
     times. The file is also searched in the current include path and
     in the extension-repository.

-extension
     Mostly equivalent to `-prelude '(define-extension <NAME>)'', where
     `<NAME>' is the basename of the currently compiled file. Note that
     if you want to compile a file as a normal (dynamically loadable)
     extension library, you should also pass the `-shared' option.

-feature SYMBOL
     Registers `SYMBOL' to be a valid feature identifier for
     `cond-expand'. Multiple symbols may be given, if comma-separated.

-fixnum-arithmetic
     Equivalent to `(fixnum-arithmetic)' declaration. Assume all
     mathematical operations use small integer arguments.

-heap-size NUMBER
     Sets a fixed heap size of the generated executable to `NUMBER'
     bytes. The parameter may be followed by a  `M' (`m') or `K' (`k')
     suffix which stand for mega- and kilobytes, respectively.  The
     default heap size is 5 kilobytes. Note that only half of it is in
     use at every given time.

-heap-initial-size NUMBER
     Sets the size that the heap of the compiled application should
     have at startup time.

-heap-growth PERCENTAGE
     Sets the heap-growth rate for the compiled program at compile time
     (see: `-:hg').

-heap-shrinkage PERCENTAGE
     Sets the heap-shrinkage rate for the compiled program at compile
     time (see: `-:hs').

-help
     Print a summary of available options and the format of the command
     line parameters and exit the compiler.

-import FILENAME
     Read exports from linked or loaded libraries from given file. See
     also `-check-imports'. This is equivalent to declaring `(declare
     (import FILENAME))'. Implies `-check-imports'.

-include-path PATHNAME
     Specifies an additional search path for files included via the
     `include' special form. This option may be given multiple times.
     If the environment variable `CHICKEN_INCLUDE_PATH' is set, it
     should contain a list of alternative include pathnames separated
     by `;'.

-inline
     Enable procedure inlining for known procedures of a size below the
     threshold (which can be set through the `-inline-limit' option).

-inline-limit THRESHOLD
     Sets the maximum size of a potentially inlinable procedure. The
     default threshold is `10'.

-keyword-style STYLE
     Enables alternative keyword syntax, where `STYLE' may be either
     `prefix' (as in Common Lisp), `suffix' (as in DSSSL) or `none'.
     Any other value is ignored. The default is `suffix'.

-keep-shadowed-macros
     Do not remove macro definitions with the same name as assigned
     toplevel variables (the default is to remove the macro definition).

-lambda-lift
     Enable the optimization known as lambda-lifting.

-no-lambda-info
     Don't emit additional information for each `lambda' expression
     (currently the argument-list, after alpha-conversion/renaming).

-no-trace
     Disable generation of tracing information. If a compiled
     executable should halt due to a runtime error, then a list of the
     name and the line-number (if available) of the last procedure
     calls is printed, unless `-no-trace' is specified. With this
     option the generated code is slightly faster.

-no-warnings
     Disable generation of compiler warnings.

-nursery NUMBER

-stack-size NUMBER
     Sets the size of the first heap-generation of the generated
     executable to `NUMBER' bytes. The parameter may be followed by a
     `M' (`m') or `K' (`k') suffix.  The default stack-size depends on
     the target platform.

-optimize-leaf-routines
     Enable leaf routine optimization.

-optimize-level LEVEL
     Enables certain sets of optimization options. `LEVEL' should be an
     integer.



    -optimize-level 0          does nothing.
    -optimize-level 1          is equivalent to -optimize-leaf-routines
    -optimize-level 2          is currently the same as -optimize-level 1
    -optimize-level 3          is equivalent to -optimize-leaf-routines -unsafe
-output-file FILENAME
     Specifies the pathname of the generated C file. Default is
     `FILENAME.c'.

-postlude EXPRESSIONS
     Add `EXPRESSIONS' after all other toplevel expressions in the
     compiled file.  This option may be given multiple times.
     Processing of this option takes place after processing of
     `-epilogue'.

-prelude EXPRESSIONS
     Add `EXPRESSIONS' before all other toplevel expressions in the
     compiled file.  This option may be given multiple times.
     Processing of this option takes place before processing of
     `-prologue'.

-profile

-accumulate-profile
     Instruments the source code to count procedure calls and execution
     times. After the program terminates (either via an explicit `exit'
     or implicitly), profiling statistics are written to a file named
     `PROFILE'. Each line of the generated file contains a list with
     the procedure name, the number of calls and the time spent
     executing it. Use the `chicken-profile' program to display the
     profiling information in a more user-friendly form. Enter
     `chicken-profile' with no arguments at the command line to get a
     list of available options. The `-accumulate-profile' option is
     similar to `-profile', but the resulting profile information will
     be appended to any existing `PROFILE' file. `chicken-profile' will
     merge and sum up the accumulated timing information, if several
     entries for the same procedure calls exist.

-profile-name FILENAME
     Specifies name of the generated profile information (which
     defaults to `PROFILE'. Implies `-profile'.

-prologue FILENAME
     Includes the file named `FILENAME' at the start of the compiled
     source file.  The include-path is not searched. This option may be
     given multiple times.

-quiet
     Disables output of compile information.

-raw
     Disables the generation of any implicit code that uses the Scheme
     libraries (that is all runtime system files besides `runtime.c'
     and `chicken.h').

-require-extension NAME
     Loads the extension `NAME' before the compilation process
     commences. This is identical to adding `(require-extension NAME)'
     at the start of the compiled program. If `-uses NAME' is also
     given on the command line, then any occurrences of
     `-require-extension NAME' are replaced with `(declare (uses
     NAME))'. Multiple names may be given and should be separated by
     `,'.

-run-time-macros
     Makes macros also available at run-time. By default macros are not
     available at run-time.

-to-stdout
     Write compiled code to standard output instead of creating a `.c'
     file.

-unit NAME
     Compile this file as a library unit. Equivalent to `-prelude
     "(declare (unit NAME))"'

-unsafe
     Disable runtime safety checks.

-unsafe-libraries
     Marks the generated file for being linked with the unsafe runtime
     system. This should be used when generating shared object files
     that are to be loaded dynamically. If the marker is present, any
     attempt to load code compiled with this option will signal an
     error.

-uses NAME
     Use definitions from the library unit `NAME'. This is equivalent
     to `-prelude "(declare (uses NAME))"'. Multiple arguments may be
     given, separated by `,'.

-no-usual-integrations
     Specifies that standard procedures and certain internal procedures
     may be redefined, and can not be inlined. This is equivalent to
     declaring `(not usual-integrations)'.

-version
     Prints the version and some copyright information and exit the
     compiler.

-verbose
     Prints progress information to standard output during compilation.

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


File: chicken.info,  Node: Using the compiler - Runtime options,  Next: Using the compiler - Examples,  Prev: Using the compiler - Compiler command line format,  Up: Using the compiler

4.2 Runtime options
===================

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

`-:?'
     Shows a list of the available runtime options and exits the
     program.

`-:aNUMBER'
     Specifies the length of the buffer for recording a trace of the
     last invoked procedures. Defaults to 16.

`-:b'
     Enter a read-eval-print-loop when an error is encountered.

`-:B'
     Sounds a bell (ASCII 7) on every major garbage collection.

`-:c'
     Forces console mode. Currently this is only used in the
     interpreter (`csi') to force output of the `#;N>' prompt even if
     stdin is not a terminal (for example if running in an `emacs'
     buffer under Windows).

`-:d'
     Prints some debug-information at runtime.

`-:D'
     Prints some more debug-information at runtime.

`-:fNUMBER'
     Specifies the maximal number of currently pending finalizers
     before finalization is forced.

`-:hNUMBER'
     Specifies fixed heap size

`-:hgPERCENTAGE'
     Sets the growth rate of the heap in percent. If the heap is
     exhausted, then it will grow by `PERCENTAGE'. The default is 200.

`-:hiNUMBER'
     Specifies the initial heap size

`-:hmNUMBER'
     Specifies a maximal heap size. The default is (2GB - 15).

`-:hsPERCENTAGE'
     Sets the shrink rate of the heap in percent. If no more than a
     quarter of `PERCENTAGE' of the heap is used, then it will shrink
     to `PERCENTAGE'. The default is 50.  Note: If you want to make
     sure that the heap never shrinks, specify a value of `0'.  (this
     can be useful in situations where an optimal heap-size is known in
     advance).

`-:o'
     Disables detection of stack overflows at run-time.

`-:r'
     Writes trace output to stderr. This option has no effect with in
     files compiled with the `-no-trace' options.

`-:sNUMBER'
     Specifies stack size.

`-:tNUMBER'
     Specifies symbol table size.

`-:w'
     Enables garbage collection of unused symbols. By default unused
     and unbound symbols are not garbage collected.

`-:x'
     Raises uncaught exceptions of separately spawned threads in
     primordial thread. By default uncaught exceptions in separate
     threads are not handled, unless the primordial one explicitly
     joins them. When warnings are enabled (the default) and `-:x' is
     not given, a warning will be shown, though.

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


File: chicken.info,  Node: Using the compiler - Examples,  Next: Using the compiler - Extending the compiler,  Prev: Using the compiler - Runtime options,  Up: Using the compiler

4.3 Examples
============

* Menu:

* Using the compiler - Examples - A simple example ;with one source file;::
* Using the compiler - Examples - An example with multiple files::


File: chicken.info,  Node: Using the compiler - Examples - A simple example ;with one source file;,  Next: Using the compiler - Examples - An example with multiple files,  Up: Using the compiler - Examples

4.3.1 A simple example (with one source file)
---------------------------------------------

* Menu:

* Using the compiler - Examples - A simple example ;with one source file; - Writing your source file::
* Using the compiler - Examples - A simple example ;with one source file; - Compiling your program::
* Using the compiler - Examples - A simple example ;with one source file; - Running your program::

   To compile a Scheme program (assuming a UNIX-like environment)
consisting of a single source file, perform the following steps.


File: chicken.info,  Node: Using the compiler - Examples - A simple example ;with one source file; - Writing your source file,  Next: Using the compiler - Examples - A simple example ;with one source file; - Compiling your program,  Up: Using the compiler - Examples - A simple example ;with one source file;

4.3.1.1 Writing your source file
................................

In this example we will assume your source file is called `foo.scm':

     _;;; foo.scm
     _
     (*define* (*fac* n)
       (*if* (zero? n)
           1
           (* n (fac (- n 1))) ) )

     (write (fac 10))
     (newline)


File: chicken.info,  Node: Using the compiler - Examples - A simple example ;with one source file; - Compiling your program,  Next: Using the compiler - Examples - A simple example ;with one source file; - Running your program,  Prev: Using the compiler - Examples - A simple example ;with one source file; - Writing your source file,  Up: Using the compiler - Examples - A simple example ;with one source file;

4.3.1.2 Compiling your program
..............................

Compile the file `foo.scm':


% csc foo.scm
 This will produce the `foo' executable:


% ls
foo  foo.scm


File: chicken.info,  Node: Using the compiler - Examples - A simple example ;with one source file; - Running your program,  Prev: Using the compiler - Examples - A simple example ;with one source file; - Compiling your program,  Up: Using the compiler - Examples - A simple example ;with one source file;

4.3.1.3 Running your program
............................

To run your newly compiled executable use:


% foo
3628800
 If you get a `foo: command not found' error, you might want to try
with `./foo' instead (or, in Unix machines, modify your `PATH'
environment variable to include your current directory).


File: chicken.info,  Node: Using the compiler - Examples - An example with multiple files,  Prev: Using the compiler - Examples - A simple example ;with one source file;,  Up: Using the compiler - Examples

4.3.2 An example with multiple files
------------------------------------

* Menu:

* Using the compiler - Examples - An example with multiple files - Writing your source files::
* Using the compiler - Examples - An example with multiple files - Compiling and running your program::

   If multiple bodies of Scheme code are to be combined into a single
executable, then we have to compile each file and link the resulting
object files together with the runtime system.

   Let's consider an example where your program consists of multiple
source files.


File: chicken.info,  Node: Using the compiler - Examples - An example with multiple files - Writing your source files,  Next: Using the compiler - Examples - An example with multiple files - Compiling and running your program,  Up: Using the compiler - Examples - An example with multiple files

4.3.2.1 Writing your source files
.................................

The declarations in these files specify which of the compiled files is
the main module, and which is the library module. An executable can
only have one main module, since a program has only a single
entry-point. In this case `foo.scm' is the main module, because it
doesn't have a `unit' declaration:

     _;;; foo.scm
     _
     _; The declaration marks this source file as dependant on the symbols provided
     __; by the bar unit:
     _(declare (uses bar))

     (write (fac 10)) (newline)
   `bar.scm' will be our library:

     _;;; bar.scm
     _
     _; The declaration marks this source file as the bar unit.  The names of the
     __; units and your files don't need to match.
     _(declare (unit bar))

     (*define* (*fac* n)
       (*if* (zero? n)
           1
           (* n (fac (- n 1))) ) )


File: chicken.info,  Node: Using the compiler - Examples - An example with multiple files - Compiling and running your program,  Prev: Using the compiler - Examples - An example with multiple files - Writing your source files,  Up: Using the compiler - Examples - An example with multiple files

4.3.2.2 Compiling and running your program
..........................................

You should compile your two files with the following commands:


% csc -c bar.scm
% csc -c foo.scm
 That should produce two files, `bar.o' and `foo.o'. They contain the
code from your source files in compiled form.

   To link your compiled files use the following command:


% csc foo.o bar.o -o foo
 This should produce the `foo' executable, which you can run just as in
the previous example. At this point you can also erase the `*.o' files.

   You could avoid one step and link the two files just as `foo.scm' is
compiled:


% csc -c bar.scm
% csc foo.scm bar.o -o foo
 Note that if you want to distribute your program, you might want it to
follow the GNU Coding Standards.  One relatively easy way to achieve
this is to use Autoconf and Automake, two tools made for this specific
purpose.


File: chicken.info,  Node: Using the compiler - Extending the compiler,  Next: Using the compiler - Distributing compiled C files,  Prev: Using the compiler - Examples,  Up: Using the compiler

4.4 Extending the compiler
==========================

The compiler supplies a couple of hooks to add user-level passes to the
compilation process. Before compilation commences any Scheme source
files or compiled code specified using the `-extend' option are loaded
and evaluated.  The parameters `user-options-pass, user-read-pass,
user-preprocessor-pass, user-pass, user-pass-2' and
`user-post-analysis-pass' can be set to procedures that are called to
perform certain compilation passes instead of the usual processing (for
more information about parameters see: *Note Supported language:
Supported language.

[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 every performed
     program analysis pass. The procedure (when defined) will be called
     with seven arguments: a symbol indicating the analysis pass, the
     program database, the current node graph, 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, a pass iteration count, and an analysis
     continuation flag. 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. The pass iteration count currently is meaningful
     only for the 'opt pass. The analysis continuation flag will be
     `#f' for the last 'opt pass. For information about the contents of
     the program database contact the author.

   Loaded code (via the `-extend' option) has access to the library
units `extras, srfi-1, srfi-4, utils, regex' and the pattern matching
macros.  Multithreading is not available.

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


File: chicken.info,  Node: Using the compiler - Distributing compiled C files,  Prev: Using the compiler - Extending the compiler,  Up: Using the compiler

4.5 Distributing compiled C files
=================================

It is relatively easy to create distributions of Scheme projects that
have been compiled to C.  The runtime system of CHICKEN consists of
only two handcoded C files (`runtime.c' and `chicken.h'), plus the file
`chicken-config.h', which is generated by the build process. All other
modules of the runtime system and the extension libraries are just
compiled Scheme code. The following example shows a minimal
application, which should run without changes on the most frequent
operating systems, like Windows, Linux or FreeBSD:

   Let's take a simple example.

     _; hello.scm
     _
     (print *"Hello, world!"*)


 % chicken hello.scm -optimize-level 3 -output-file hello.c
 Compiled to C, we get `hello.c'. We need the files `chicken.h' and
`runtime.c', which contain the basic runtime system, plus the three
basic library files `library.c', `eval.c' and `extras.c' which contain
the same functionality as the library linked into a plain
CHICKEN-compiled application, or which is available by default in the
interpreter, `csi':


 % cd /tmp
 %echo '(print "Hello World.")' > hello.scm
 % cp $CHICKEN_BUILD/runtime.c .
 % cp $CHICKEN_BUILD/library.c .
 % cp $CHICKEN_BUILD/eval.c    .
 % cp $CHICKEN_BUILD/extras.c  .
 % gcc -static -Os -fomit-frame-pointer runtime.c library.c eval.c \
   extras.c hello.c -o hello -lm
 Now we have all files together, and can create an tarball containing
all the files:


% tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
% gzip hello.tar
 This is naturally rather simplistic. Things like enabling dynamic
loading, estimating the optimal stack-size and selecting supported
features of the host system would need more configuration- and
build-time support. All this can be addressed using more elaborate
build-scripts, makefiles or by using autoconf/automake.

   Note also that the size of the application can still be reduced by
removing `extras' and `eval' and compiling `hello.scm' with the
`-explicit-use' option.

   For more information, study the CHICKEN source code and/or get in
contact with the author.

   Previous: *Note The User's Manual: The User's Manual.

   Next: *Note Using the interpreter: Using the interpreter.


File: chicken.info,  Node: Using the interpreter,  Next: Supported language,  Prev: Using the compiler,  Up: Top

5 Using the interpreter
***********************

* Menu:

* Using the interpreter - Interpreter command line format::
* Using the interpreter - Writing Scheme scripts::
* Using the interpreter - Toplevel commands::
* Using the interpreter - toplevel-command::
* Using the interpreter - History access::
* Using the interpreter - set-describer!::
* Using the interpreter - Auto-completion and edition::
* Using the interpreter - Accessing documentation::

   CHICKEN provides an interpreter named `csi' for evaluating Scheme
programs and expressions interactively.


File: chicken.info,  Node: Using the interpreter - Interpreter command line format,  Next: Using the interpreter - Writing Scheme scripts,  Up: Using the interpreter

5.1 Interpreter command line format
===================================

`csi {FILENAME|OPTION'}

   where `FILENAME' specifies a file with Scheme source-code.  If the
extension of the source file is `.scm', it may be omitted. The runtime
options described in Compiler command line format
(http://galinha.ucpel.tche.br/Using%20the%20compiler#Compiler%20command%20line%20format)
are also available for the interpreter.  If the environment variable
`CSI_OPTIONS' is set to a list of options, then these options are
additionally passed to every direct or indirect invocation of `csi'.
Please note that runtime options (like `-:...') can not be passed using
this method. The options recognized by the interpreter are:

-
     Ignore everything on the command-line following this marker.
     Runtime options (`-:...') are still recognized.

-i  -case-insensitive
     Enables the reader to read symbols case insensitive. The default
     is to read case sensitive (in violation of R5RS).  This option
     registers the `case-insensitive' feature identifier.

-b  -batch
     Quit the interpreter after processing all command line options.

-e  -eval EXPRESSIONS
     Evaluate `EXPRESSIONS'. This option implies `-batch' and `-quiet',
     so no startup message will be printed and the interpreter exits
     after processing all `-eval' options and/or loading files given on
     the command-line.

-p  -print EXPRESSIONS
     Evaluate `EXPRESSIONS' and print the results of each expression
     using `print'. Implies `-batch' and `-quiet'.

-P  -pretty-print EXPRESSIONS
     Evaluate `EXPRESSIONS' and print the results of each expression
     using `pretty-print'. Implies `-batch' and `-quiet'.

-D  -feature SYMBOL
     Registers `SYMBOL' to be a valid feature identifier for
     `cond-expand' and `feature?'.

-h  -help
     Write a summary of the available command line options to standard
     output and exit.

-I  -include-path PATHNAME
     Specifies an alternative search-path for files included via the
     `include' special form. This option may be given multiple times.
     If the environment variable `CHICKEN_INCLUDE_PATH' is set, it
     should contain a list of alternative include pathnames separated
     by `;'.

-k  -keyword-style STYLE
     Enables alternative keyword syntax, where `STYLE' may be either
     `prefix' (as in Common Lisp) or `suffix' (as in DSSSL). Any other
     value is ignored.

-n  -no-init
     Do not load initialization-file. If this option is not given and
     the file `./.csirc' or `$HOME/.csirc' exists, then it is loaded
     before the read-eval-print loop commences.

-w  -no-warnings
     Disables any warnings that might be issued by the reader or
     evaluated code.

-q  -quiet
     Do not print a startup message. Also disables generation of
     call-trace information for interpreted code.

-s  -script PATHNAME
     This is equivalent to `-batch -quiet -no-init PATHNAME'. Arguments
     following `PATHNAME' are available by using
     `command-line-arguments' and are not processed as interpreter
     options. Extra options in the environment variable `CSI_OPTIONS'
     are ignored.

-ss PATHNAME
     The same as `-s PATHNAME' but invokes the procedure `main' with
     the value of `(command-line-arguments)' as its single argument. If
     the main procedure returns an integer result, then the interpreter
     is terminated, returning the integer as the status code back to
     the invoking process. Any other result terminates the interpreter
     with a zero exit status.

-R  -require-extension NAME
     Equivalent to evaluating `(require-extension NAME)'.

-v  -version
     Write the banner with version information to standard output and
     exit.



File: chicken.info,  Node: Using the interpreter - Writing Scheme scripts,  Next: Using the interpreter - Toplevel commands,  Prev: Using the interpreter - Interpreter command line format,  Up: Using the interpreter

5.2 Writing Scheme scripts
==========================

Since UNIX shells use the `#!' notation for starting scripts, anything
following the characters `#!' is ignored, with the exception of the
special symbols `#!optional, #!key, #!rest' and `#!eof'.

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


% cat foo
#! /usr/local/bin/csi -script
(print (eval (with-input-from-string
                (car (command-line-arguments))
                 read)))

% chmod +x foo
% foo "(+ 3 4)"
7
 The parameter `command-line-arguments' is set to a list of the
parameters that were passed to the Scheme script.  Scripts can be
compiled to standalone executables (don't forget to declare used
library units).

   CHICKEN supports writing shell scripts in Scheme for these platforms
as well, using a slightly different approach. The first example would
look like this on Windows:


C:>type foo.bat
@;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
(print (eval (with-input-from-string
                (car (command-line-arguments))
                read)))

C:>foo "(+ 3 4)"
7
 Like UNIX scripts, batch files can be compiled. Windows batch scripts
do not accept more than 8 arguments.

   Since it is sometimes useful to run a script into the interpreter
without actually running it (for example to test specific parts of it),
the option `-ss' can be used as an alternative to `-script'. `-ss
PATHNAME' is equivalent to `-script PATHNAME' but invokes `(main
(command-line-arguments))' after loading all top-level forms of the
script file. The result of `main' is returned as the exit status to the
shell. Any non-numeric result exits with status zero:


% cat hi.scm
(define (main args)
  (print "Hi, " (car args))
  0)
% csi -ss hi.scm you
Hi, you
% csi -q
#;1> ,l hi.scm
#;2> (main (list "ye all"))
Hi, ye all
0
#;3>


File: chicken.info,  Node: Using the interpreter - Toplevel commands,  Next: Using the interpreter - toplevel-command,  Prev: Using the interpreter - Writing Scheme scripts,  Up: Using the interpreter

5.3 Toplevel commands
=====================

The toplevel loop understands a number of special commands:

,?
     Show summary of available toplevel commands.

,l FILENAME ...
     Load files with given `FILENAME's

,ln FILENAME ...
     Load files and print result(s) of each top-level expression.

,p EXP
     Pretty-print evaluated expression `EXP'.

,d EXP
     Describe result of evaluated expression `EXP'.

,du EXP
     Dump contents of the result of evaluated expression `EXP'.

,dur EXP N
     Dump `N' bytes of the result of evaluated expression `EXP'.

,exn
     Describes the last exception that occurred and adds it to the
     result history (it can be accessed using the `#' notation).

,q
     Quit the interpreter.

,r
     Show system information.

,s TEXT ...
     Execute shell-command.

,t EXP
     Evaluate form and print elapsed time.

,x EXP
     Pretty-print macroexpanded expression `EXP' (the expression is not
     evaluated).

,tr SYMBOL ...
     Enables tracing of the toplevel procedures with the given names.


     #_;1> (fac 10)                       ==> 3628800
     _#_;2> ,tr fac
     _#_;3> (fac 3)
     _|(fac 3)
     | (fac 2)
     |  (fac 1)
     |   (fac 0)
     |   fac -> 1
     |  fac -> 1
     | fac -> 2
     |fac -> 6                          =*=>* 6
     #_;4> ,utr fac
     _#_;5> (fac 3)                        ==> 6
     _
   k

,utr SYMBOL ...
     Disables tracing of the given toplevel procedures.

,br SYMBOL ...
     Sets a breakpoint at the procedures named `SYMBOL ...'. Breakpoint
     can also be trigged using the `breakpoint' procedure.

,ubr SYMBOL ...
     Removes breakpoints.

,c
     Continues execution from the last invoked breakpoint.

,breakall
     Enable breakpoints for all threads (this is the default).

,breakonly THREAD
     Enable breakpoints only for the thread returned by the expression
     `THREAD'.

,info
     Lists traced procedures and breakpoints.

,step EXPR
     Evaluates `EXPR' in single-stepping mode. On each procedure call
     you will be presented with a menu that allows stepping to the next
     call, leaving single-stepping mode or triggering a breakpoint.
     Note that you will see some internal calls, and unsafe or heavily
     optimized compiled code might not be stepped at all.
     Single-stepping mode is also possible by invoking the `singlestep'
     procedure.

   You can define your own toplevel commands using the
`toplevel-command' procedure:


File: chicken.info,  Node: Using the interpreter - toplevel-command,  Next: Using the interpreter - History access,  Prev: Using the interpreter - Toplevel commands,  Up: Using the interpreter

5.4 toplevel-command
====================


[procedure] (toplevel-command SYMBOL PROC [HELPSTRING])
 Defines or redefines a toplevel interpreter command which 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.


File: chicken.info,  Node: Using the interpreter - History access,  Next: Using the interpreter - set-describer!,  Prev: Using the interpreter - toplevel-command,  Up: Using the interpreter

5.5 History access
==================

The interpreter toplevel accepts the special object `#[INDEX]' which
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 the
value returned is implicitly quoted.


File: chicken.info,  Node: Using the interpreter - set-describer!,  Next: Using the interpreter - Auto-completion and edition,  Prev: Using the interpreter - History access,  Up: Using the interpreter

5.6 set-describer!
==================


[procedure] (set-describer! TAG PROC)
 Sets a custom description handler that invokes `PROC' when the `,d'
command is invoked with a record-type object that has the type `TAG' (a
symbol). `PROC' is called with two arguments: the object to be
described and an output-port. It should write a possibly useful textual
description of the object to the passed output-port. For example:


#;1> (define-record point x y)
#;2> (set-describer! 'point
       (lambda (pt o)
         (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
#;3> ,d (make-point 1 2)
a point with x=1 and y=2


File: chicken.info,  Node: Using the interpreter - Auto-completion and edition,  Next: Using the interpreter - Accessing documentation,  Prev: Using the interpreter - set-describer!,  Up: Using the interpreter

5.7 Auto-completion and edition
===============================

On platforms that support it, it is possible to get auto-completion of
symbols, history (over different `csi' sessions) and a more
feature-full editor for the expressions you type using the
http://www.call-with-current-continuation.org/eggs/readline.html
(http://www.call-with-current-continuation.org/eggs/readline.html) egg
by Tony Garnock Jones. It is very useful for interactive use of csi.

   To enable it install the egg and put this in your `~/.csirc' file:


(use readline regex)
(current-input-port (make-gnu-readline-port))
(gnu-history-install-file-manager
  (string-append (or (getenv "HOME") ".") "/.csi.history"))
 More details are available in the egg's documentation
(http://www.call-with-current-continuation.org/eggs/readline.html).


File: chicken.info,  Node: Using the interpreter - Accessing documentation,  Prev: Using the interpreter - Auto-completion and edition,  Up: Using the interpreter

5.8 Accessing documentation
===========================

You can access the manual directly from `csi' using the man
(http://www.call-with-current-continuation.org/eggs/man.html) extension
by Mario Domenech Goulart.

   To enable it install the egg and put this in your `~/.csirc' file:


(use man)
(man:load)
 Then, in `csi', you can search for definitions using `man:search' as
in:


(man:search "case")
 Note that the search uses regular expressions. To view the
documentation for one entry from the manual, use `man:help' as in:


(man:help "case-lambda")
 Note: Currently the documentation provided by the `man' extension
corresponds to Chicken's 2.429, one of the last releases whose
documentation was in the texinfo format (the format the `man' extension
parses).

   Previous: *Note Using the compiler: Using the compiler.

   Next: *Note Supported language: Supported language.


File: chicken.info,  Node: Supported language,  Next: Deviations from the standard,  Prev: Using the interpreter,  Up: Top

6 Supported language
********************

   * *Note Deviations from the standard: Deviations from the standard.

   * *Note Extensions to the standard: Extensions to the standard.

   * *Note Non-standard read syntax: Non-standard read syntax.

   * *Note Non-standard macros and special forms: Non-standard macros
     and special forms.

   * *Note Pattern matching: Pattern matching.

   * *Note Declarations: Declarations.

   * *Note Parameters: Parameters.

   * *Note Unit library: Unit library. basic Scheme definitions

   * *Note Unit eval: Unit eval. evaluation and macro-handling

   * *Note Unit data-structures: Unit data-structures. data structures

   * *Note Unit ports: Unit ports. I/O ports

   * *Note Unit files: Unit files. File and pathname operations

   * *Note Unit extras: Unit extras. useful utility definitions

   * *Note Unit srfi-1: Unit srfi-1. list library

   * *Note Unit srfi-4: Unit srfi-4. homogeneous numeric vectors

   * *Note Unit srfi-13: Unit srfi-13. string library

   * *Note Unit srfi-14: Unit srfi-14. character set library

   * *Note Unit srfi-69: Unit srfi-69. hash tables

   * *Note Unit match: Unit match. pattern matching runtime-support

   * *Note Unit regex: Unit regex. regular expressions

   * *Note Unit srfi-18: Unit srfi-18. multithreading

   * *Note Unit posix: Unit posix. Unix-like services

   * *Note Unit utils: Unit utils. Shell scripting and file operations

   * *Note Unit tcp: Unit tcp. basic TCP-sockets

   * *Note Unit lolevel: Unit lolevel. low-level operations

Previous: *Note Using the interpreter: Using the interpreter.

   Next: *Note Interface to external functions and variables: Interface
to external functions and variables.


File: chicken.info,  Node: Deviations from the standard,  Next: Extensions to the standard,  Prev: Supported language,  Up: Top

7 Deviations from the standard
******************************

Identifiers are by default case-sensitive (see Compiler command line
format
(http://galinha.ucpel.tche.br:8080/Using%20the%20compiler#Compiler%20command%20line%20format)).

   [4.1.3] The maximal number of arguments that may be passed to a
compiled procedure or macro is 120.  A macro-definition that has a
single rest-parameter can have any number of arguments.

   [4.2.2] `letrec' does evaluate the initial values for the bound
variables sequentially and not in parallel, that is:


 (letrec ((x 1) (y 2)) (cons x y))
 is equivalent to


 (let ((x (void)) (y (void)))
   (set! x 1)
   (set! y 2)
   (cons x y) )
 where R5RS requires


 (let ((x (void)) (y (void)))
   (let ((tmp1 1) (tmp2 2))
     (set! x tmp1)
     (set! y tmp2)
     (cons x y) ) )
 [4.3] `syntax-rules' macros are not provided but available separately.

   [6.1] `equal?' compares all structured data recursively, while R5RS
specifies that `eqv?' is used for data other than pairs, strings and
vectors.

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

   [6.2.5] There is no built-in support for rationals, complex numbers
or extended-precision integers (bignums). The routines `complex?',
`real?' and `rational?' are identical to the standard procedure
`number?'. The procedures `numerator', `denominator', `rationalize',
`make-rectangular' and `make-polar' are not implemented. Fixnums are
limited to ±2<nowiki><sup>30</sup></nowiki> (or
±2<nowiki><sup>62</sup></nowiki> on 64-bit hardware).  Support for
extended numbers is available as a separate package, provided the GNU
multiprecision library is installed.

   [6.2.6] The procedure `string->number' does not obey read/write
invariance on inexact numbers.

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

   [6.5] Code evaluated in `scheme-report-environment' or
`null-environment' still sees non-standard syntax.

   [6.6.2] The procedure `char-ready?' always returns `#t' for terminal
ports.  The procedure `read' does not obey read/write invariance on
inexact numbers.

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

   [6.6.4] The `transcript-on' and `transcript-off' procedures are not
implemented.

   Previous: *Note Supported language: Supported language.

   Next: *Note Extensions to the standard: Extensions to the standard.


File: chicken.info,  Node: Extensions to the standard,  Next: Non-standard read syntax,  Prev: Deviations from the standard,  Up: Top

8 Extensions to the standard
****************************

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

   [2.3] The brackets `[ ... ]' and the braces ` { ... } ' are provided
as an alternative syntax for `( ... )'.  A number of reader extensions
is provided. See *Note Non-standard read syntax: Non-standard read
syntax.

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

   [4.1.4] Extended DSSSL style lambda lists are supported. DSSSL
parameter lists are defined by the following grammar:


<parameter-list> ==> <required-parameter>*
                     [(#!optional <optional-parameter>*)]
                     [(#!rest <rest-parameter>)]
                     [(#!key <keyword-parameter>*)]
<required-parameter> ==> <ident>
<optional-parameter> ==> <ident>
                         | (<ident> <initializer>)
<rest-parameter> ==> <ident>
<keyword-parameter> ==> <ident>
                        | (<ident> <initializer>)
<initializer> ==> <expr>
 When a procedure is applied to a list of arguments, the parameters and
arguments are processed from left to right as follows:

   * Required-parameters are bound to successive arguments starting
     with the first argument. It shall be an error if there are fewer
     arguments than required-parameters.

   * Next, the optional-parameters are bound with the remaining
     arguments. If there are fewer arguments than optional-parameters,
     then the remaining optional-parameters are bound to the result of
     the evaluation of their corresponding <initializer>, if one was
     specified, otherwise `#f'. The corresponding <initializer> is
     evaluated in an environment in which all previous parameters have
     been bound.

   * If there is a rest-parameter, then it is bound to a list
     containing all the remaining arguments left over after the
     argument bindings with required-parameters and optional-parameters
     have been made.

   * If `#!key' was specified in the parameter-list, there should be an
     even number of remaining arguments. These are interpreted as a
     series of pairs, where the first member of each pair is a keyword
     specifying the parameter name, and the second member is the
     corresponding value. If the same keyword occurs more than once in
     the list of arguments, then the corresponding value of the first
     keyword is the binding value. If there is no argument for a
     particular keyword-parameter, then the variable is bound to the
     result of evaluating <initializer>, if one was specified,
     otherwise `#f'. The corresponding <initializer> is evaluated in an
     environment in which all previous parameters have been bound.

   Needing a special mention is the close relationship between the
rest-parameter and possible keyword-parameters.  Declaring a
rest-parameter binds up all remaining arguments in a list, as described
above. These same remaining arguments are also used for attempted
matches with declared keyword-parameters, as described above, in which
case a matching keyword-parameter binds to the corresponding value
argument at the same time that both the keyword and value arguments are
added to the rest parameter list. Note that for efficiency reasons, the
keyword-parameter matching does nothing more than simply attempt to
match with pairs that may exist in the remaining arguments.  Extra
arguments that don't match are simply unused and forgotten if no
rest-parameter has been declared.  Because of this, the caller of a
procedure containing one or more keyword-parameters cannot rely on any
kind of system error to report wrong keywords being passed in.

   It shall be an error for an `<ident>' to appear more than once in a
parameter-list.

   If there is no rest-parameter and no keyword-parameters in the
parameter-list, then it shall be an error for any extra arguments to be
passed to the procedure.

   Example:


((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)
 [4.1.6] `set!' for unbound toplevel variables is allowed. `set!
(PROCEDURE ...) ...)' is supported, as CHICKEN implements SRFI-17
(http://srfi.schemers.org/srfi-17/srfi-17.html). [4.2.1] The `cond'
form supports SRFI-61 (http://srfi.schemers.org/srfi-61).

   [4.2.2] It is allowed for initialization values of bindings in a
`letrec' construct to refer to previous variables in the same set of
bindings, so


(letrec ((foo 123)
         (bar foo) )
  bar)
 is allowed and returns `123'.

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

   [4.2.5] Delayed expressions may return multiple values.

   [5.2.2] CHICKEN extends standard semantics by allowing internal
definitions everywhere, and not only at the beginning of a body. A set
of internal definitions is equivalent to a `letrec' form enclosing all
following expressions in the body:


(let ((foo 123))
  (bar)
  (define foo 456)
  (baz foo) )
 expands into


(let ((foo 123))
  (bar)
  (letrec ((foo 456))
    (baz foo) ) )
 [5.2] `define' with a single argument is allowed and initializes the
toplevel or local binding to an unspecified value. CHICKEN supports
_curried_ definitions, where the variable name may also be a list
specifying a name and a nested lambda list. So


(define ((make-adder x) y) (+ x y))
 is equivalent to


(define (make-adder x) (lambda (y) (+ x y)))
 [6] CHICKEN provides numerous non-standard procedures. See the manual
sections on library units for more information.

   [6.2.4] The special IEEE floating-point numbers _+nan_, _+inf_ and
_-inf_ are supported, as is negative zero.

   [6.3.4] User defined character names are supported. See `char-name'.
Characters can be given in hexadecimal notation using the _#\xXX_
syntax where _XX_ specifies the  character code. Character codes above
255 are supported and can be read (and are written) using the _#\uXXXX_
and _#\UXXXXXXXX_ notations.

   Non-standard characters names supported are `#\tab', `#\linefeed',
`#\return', `#\alarm', `#\vtab', `#\nul', `#\page', `#\esc', `#\delete'
and `#\backspace'.

   [6.3.5]  CHICKEN supports special characters preceded with a
backslash _\_ in quoted string constants. _\n_ denotes the
newline-character, _\r_ carriage return, _\b_ backspace, _\t_ TAB, _\v_
vertical TAB, _\a_ alarm, _\f_ formfeed, _\xXX_ a character with the
code `XX' in hex and  _\uXXXX_ (and _\UXXXXXXXX_) a unicode character
with the code `XXXX'. The latter is encoded in UTF-8 format.

   The third argument to `substring' is optional and defaults to the
length of the string.

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

   Implicit non-multival continuations accept multiple values by
discarding all but the first result. Zero values result in the
continuation receiving an unspecified value. Note that this slight
relaxation of the behaviour of returning mulitple values to
non-multival continuations does not apply to explicit continuations
(created with `call-with-current-continuation').

   [6.5] The second argument to `eval' is optional and defaults to the
value of `(interaction-environment)'. `scheme-report-environment' and
`null-environment' accept an optional 2nd parameter: if not `#f' (which
is the default), toplevel bindings to standard procedures are mutable
and new toplevel bindings may be introduced.

   [6.6] The _tilde_ character (`~') is automatically expanded in
pathnames. Additionally, if a pathname starts with `$VARIABLE...', then
the prefix is replaced by the value of the given environment variable.

   [6.6.1] if the procedures `current-input-port' and
`current-output-port' are called with an argument (which should be a
port), then that argument is selected as the new current input- and
output-port, respectively.  The procedures `open-input-file',
`open-output-file', `with-input-from-file', `with-output-to-file',
`call-with-input-file' and `call-with-output-file' accept an optional
second (or third) argument which should be one or more keywords, if
supplied. These arguments specify the mode in which the file is opened.
Possible values are the keywords `#:text', `#:binary' or `#:append'.

   [6.7] The `exit' procedure exits a program right away and does _not_
invoke pending `dynamic-wind' thunks.

   Previous: *Note Deviations from the standard: Deviations from the
standard.

   Next: *Note Non-standard read syntax: Non-standard read syntax.


File: chicken.info,  Node: Non-standard read syntax,  Next: Non-standard macros and special forms,  Prev: Extensions to the standard,  Up: Top

9 Non-standard read syntax
**************************

* Menu:

* Non-standard read syntax - Multiline Block Comment::
* Non-standard read syntax - Expression Comment::
* Non-standard read syntax - External Representation::
* Non-standard read syntax - Syntax Expression::
* Non-standard read syntax - Location Expression::
* Non-standard read syntax - Keyword::
* Non-standard read syntax - Multiline String Constant::
* Non-standard read syntax - Multiline String Constant with Embedded Expressions::
* Non-standard read syntax - Foreign Declare::
* Non-standard read syntax - Sharp Prefixed Symbol::
* Non-standard read syntax - Bang::
* Non-standard read syntax - Case Sensitive Expression::
* Non-standard read syntax - Case Insensitive Expression::
* Non-standard read syntax - Conditional Expansion::


File: chicken.info,  Node: Non-standard read syntax - Multiline Block Comment,  Next: Non-standard read syntax - Expression Comment,  Up: Non-standard read syntax

9.1 Multiline Block Comment
===========================


#| ... |#
 A multiline _block_ comment. May be nested. Implements SRFI-30
(http://srfi.schemers.org/srfi-30/srfi-30.html)


File: chicken.info,  Node: Non-standard read syntax - Expression Comment,  Next: Non-standard read syntax - External Representation,  Prev: Non-standard read syntax - Multiline Block Comment,  Up: Non-standard read syntax

9.2 Expression Comment
======================


#;EXPRESSION
 Treats `EXPRESSION' as a comment.  That is, the comment runs through
the whole S-expression, regardless of newlines, which saves you from
having to comment out every line, or add a newline in the middle of
your parens to make the commenting of the last line work, or other
things like that.


File: chicken.info,  Node: Non-standard read syntax - External Representation,  Next: Non-standard read syntax - Syntax Expression,  Prev: Non-standard read syntax - Expression Comment,  Up: Non-standard read syntax

9.3 External Representation
===========================


#,(CONSTRUCTORNAME DATUM ...)
 Allows user-defined extension of external representations. (For more
information see the documentation for SRFI-10
(http://srfi.schemers.org/srfi-10/srfi-10.html))


File: chicken.info,  Node: Non-standard read syntax - Syntax Expression,  Next: Non-standard read syntax - Location Expression,  Prev: Non-standard read syntax - External Representation,  Up: Non-standard read syntax

9.4 Syntax Expression
=====================


#'EXPRESSION
 An abbreviation for `(syntax EXPRESSION)'.


File: chicken.info,  Node: Non-standard read syntax - Location Expression,  Next: Non-standard read syntax - Keyword,  Prev: Non-standard read syntax - Syntax Expression,  Up: Non-standard read syntax

9.5 Location Expression
=======================


#$EXPRESSION
 An abbreviation for `(location EXPRESSION)'.


File: chicken.info,  Node: Non-standard read syntax - Keyword,  Next: Non-standard read syntax - Multiline String Constant,  Prev: Non-standard read syntax - Location Expression,  Up: Non-standard read syntax

9.6 Keyword
===========


#:SYMBOL
 Syntax for keywords. Keywords are symbols that evaluate to themselves,
and as such don't have to be quoted.


File: chicken.info,  Node: Non-standard read syntax - Multiline String Constant,  Next: Non-standard read syntax - Multiline String Constant with Embedded Expressions,  Prev: Non-standard read syntax - Keyword,  Up: Non-standard read syntax

9.7 Multiline String Constant
=============================


#<<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.")


File: chicken.info,  Node: Non-standard read syntax - Multiline String Constant with Embedded Expressions,  Next: Non-standard read syntax - Foreign Declare,  Prev: Non-standard read syntax - Multiline String Constant,  Up: Non-standard read syntax

9.8 Multiline String Constant with Embedded Expressions
=======================================================


#<#TAG
 Similar to `#<<', but allows substitution of embedded Scheme
expressions prefixed with `#' and optionally enclosed in curly
brackets. 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")


File: chicken.info,  Node: Non-standard read syntax - Foreign Declare,  Next: Non-standard read syntax - Sharp Prefixed Symbol,  Prev: Non-standard read syntax - Multiline String Constant with Embedded Expressions,  Up: Non-standard read syntax

9.9 Foreign Declare
===================


#> ... <#
 Abbreviation for `foreign-declare " ... ")'.


File: chicken.info,  Node: Non-standard read syntax - Sharp Prefixed Symbol,  Next: Non-standard read syntax - Bang,  Prev: Non-standard read syntax - Foreign Declare,  Up: Non-standard read syntax

9.10 Sharp Prefixed Symbol
==========================


#%...
 Reads like a normal symbol.


File: chicken.info,  Node: Non-standard read syntax - Bang,  Next: Non-standard read syntax - Case Sensitive Expression,  Prev: Non-standard read syntax - Sharp Prefixed Symbol,  Up: Non-standard read syntax

9.11 Bang
=========

* Menu:

* Non-standard read syntax - Bang - Line Comment::
* Non-standard read syntax - Bang - Eof Object::
* Non-standard read syntax - Bang - DSSSL Formal Parameter List Annotation::
* Non-standard read syntax - Bang - Read Mark Invocation::


#!...
 Interpretation depends on the directly following characters. Only the
following are recognized. Any other case results in a read error.


File: chicken.info,  Node: Non-standard read syntax - Bang - Line Comment,  Next: Non-standard read syntax - Bang - Eof Object,  Up: Non-standard read syntax - Bang

9.11.1 Line Comment
-------------------

   * If followed by whitespace or a slash, then everything up the end
     of the current line is ignored



File: chicken.info,  Node: Non-standard read syntax - Bang - Eof Object,  Next: Non-standard read syntax - Bang - DSSSL Formal Parameter List Annotation,  Prev: Non-standard read syntax - Bang - Line Comment,  Up: Non-standard read syntax - Bang

9.11.2 Eof Object
-----------------

   * If followed by the character sequence `eof', then the
     (self-evaluating) end-of-file object is returned



File: chicken.info,  Node: Non-standard read syntax - Bang - DSSSL Formal Parameter List Annotation,  Next: Non-standard read syntax - Bang - Read Mark Invocation,  Prev: Non-standard read syntax - Bang - Eof Object,  Up: Non-standard read syntax - Bang

9.11.3 DSSSL Formal Parameter List Annotation
---------------------------------------------

   * If followed by any of the character sequences `optional', `rest'
     or `key', then a symbol with the same name (and prefixed with
     `#!') is returned



File: chicken.info,  Node: Non-standard read syntax - Bang - Read Mark Invocation,  Prev: Non-standard read syntax - Bang - DSSSL Formal Parameter List Annotation,  Up: Non-standard read syntax - Bang

9.11.4 Read Mark Invocation
---------------------------

   * If a _read mark_ with the same name as the token is registered,
     then its procedure is called and the result of the read-mark
     procedure will be returned



File: chicken.info,  Node: Non-standard read syntax - Case Sensitive Expression,  Next: Non-standard read syntax - Case Insensitive Expression,  Prev: Non-standard read syntax - Bang,  Up: Non-standard read syntax

9.12 Case Sensitive Expression
==============================


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


File: chicken.info,  Node: Non-standard read syntax - Case Insensitive Expression,  Next: Non-standard read syntax - Conditional Expansion,  Prev: Non-standard read syntax - Case Sensitive Expression,  Up: Non-standard read syntax

9.13 Case Insensitive Expression
================================


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


File: chicken.info,  Node: Non-standard read syntax - Conditional Expansion,  Prev: Non-standard read syntax - Case Insensitive Expression,  Up: Non-standard read syntax

9.14 Conditional Expansion
==========================


#+FEATURE EXPR
 Equivalent to


(cond-expand (FEATURE EXPR) (else))
 Previous: *Note Extensions to the standard: Extensions to the standard.

Next: *Note Non-standard macros and special forms: Non-standard macros
and special forms.


File: chicken.info,  Node: Non-standard macros and special forms,  Next: Pattern matching,  Prev: Non-standard read syntax,  Up: Top

10 Non-standard macros and special forms
****************************************

* Menu:

* Non-standard macros and special forms - Making extra libraries and extensions available::
* Non-standard macros and special forms - Binding forms for optional arguments::
* Non-standard macros and special forms - Other binding forms::
* Non-standard macros and special forms - Substitution forms and macros::
* Non-standard macros and special forms - Conditional forms::
* Non-standard macros and special forms - Record structures::
* Non-standard macros and special forms - Other forms::


File: chicken.info,  Node: Non-standard macros and special forms - Making extra libraries and extensions available,  Next: Non-standard macros and special forms - Binding forms for optional arguments,  Up: Non-standard macros and special forms

10.1 Making extra libraries and extensions available
====================================================

* Menu:

* Non-standard macros and special forms - Making extra libraries and extensions available - require-extension::
* Non-standard macros and special forms - Making extra libraries and extensions available - define-extension::


File: chicken.info,  Node: Non-standard macros and special forms - Making extra libraries and extensions available - require-extension,  Next: Non-standard macros and special forms - Making extra libraries and extensions available - define-extension,  Up: Non-standard macros and special forms - Making extra libraries and extensions available

10.1.1 require-extension
------------------------


[syntax] (require-extension ID ...)
[syntax] (use ID ...)
 This form does all the necessary steps to make the libraries or
extensions given in `ID ...' available. It loads syntactic extensions,
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 with SRFI-55
(http://srfi.schemers.org/srfi-55/srfi-55.html) (see the SRFI-55
(http://srfi.schemers.org/srfi-55/srfi-55.html) document for more
information).

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

   * If `ID' names a built-in feature `chicken srfi-0 srfi-2 srfi-6
     srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55',
     then nothing is done.

   * If `ID' names one of the syntactic extensions `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 `ID' names an installed extension with the `syntax' or
     `require-at-runtime' attribute, then the equivalent of
     `(require-for-syntax 'ID)' is performed, probably followed by
     `(require ...)' for any run-time requirements.

   * Otherwise, `(require-extension ID)' is equivalent to `(require
     'ID)'.

   During compilation, one of the following happens instead:

   * If `ID' names a built-in feature `chicken srfi-0 srfi-2 srfi-6
     srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55',
     then nothing is done.

   * If `ID' names one of the syntactic extensions `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,
     or if the option `-uses ID' has been passed to the compiler, then
     a `(declare (uses ID))' is generated.

   * If `ID' names an installed extension with the `syntax' or
     `require-at-runtime' attribute, then the equivalent of
     `(require-for-syntax 'ID)' is performed, and code is emitted to
     `(require ...)' any needed run-time requirements.

   * 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!'

   When syntax extensions are loaded that redefine the global toplevel
macro-expander (for example the syntax-case
(http://www.call-with-current-continuation.org/eggs/syntax-case.html)
extension), then all remaining expression _in the same toplevel form_
are still expanded with the old toplevel macro-expander.


File: chicken.info,  Node: Non-standard macros and special forms - Making extra libraries and extensions available - define-extension,  Prev: Non-standard macros and special forms - Making extra libraries and extensions available - require-extension,  Up: Non-standard macros and special forms - Making extra libraries and extensions available

10.1.2 define-extension
-----------------------


[syntax] (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 of the form

     (dynamic EXPRESSION ...)
are inserted into the output as a `begin' form.

   If compiled statically (specifically if the feature
`chicken-compile-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)


File: chicken.info,  Node: Non-standard macros and special forms - Binding forms for optional arguments,  Next: Non-standard macros and special forms - Other binding forms,  Prev: Non-standard macros and special forms - Making extra libraries and extensions available,  Up: Non-standard macros and special forms

10.2 Binding forms for optional arguments
=========================================

* Menu:

* Non-standard macros and special forms - Binding forms for optional arguments - optional::
* Non-standard macros and special forms - Binding forms for optional arguments - case-lambda::
* Non-standard macros and special forms - Binding forms for optional arguments - let-optionals::
* Non-standard macros and special forms - Binding forms for optional arguments - let-optionals*::


File: chicken.info,  Node: Non-standard macros and special forms - Binding forms for optional arguments - optional,  Next: Non-standard macros and special forms - Binding forms for optional arguments - case-lambda,  Up: Non-standard macros and special forms - Binding forms for optional arguments

10.2.1 optional
---------------


[syntax] (optional ARGS DEFAULT)
 Use this form for procedures that take a single optional argument. If
`ARGS' is the empty list `DEFAULT' is evaluated and returned, otherwise
the first element of the list `ARGS'. It is an error if `ARGS' contains
more than one value.

     (*define* (*incr* x . i) (+ x (optional i 1)))
     (incr 10)                                   =*=>* 11
     (incr 12 5)                                 =*=>* 17


File: chicken.info,  Node: Non-standard macros and special forms - Binding forms for optional arguments - case-lambda,  Next: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals,  Prev: Non-standard macros and special forms - Binding forms for optional arguments - optional,  Up: Non-standard macros and special forms - Binding forms for optional arguments

10.2.2 case-lambda
------------------


[syntax] (case-lambda (LAMBDA-LIST1 EXP1 ...) ...)
 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)                      =*=>* 0
     (plus 1)                    =*=>* 1
     (plus 1 2 3)                =*=>* 6
For more information see the documentation for SRFI-16
(http://srfi.schemers.org/srfi-16/srfi-16.html)


File: chicken.info,  Node: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals,  Next: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals*,  Prev: Non-standard macros and special forms - Binding forms for optional arguments - case-lambda,  Up: Non-standard macros and special forms - Binding forms for optional arguments

10.2.3 let-optionals
--------------------


[syntax]  (let-optionals ARGS ((VAR1 DEFAULT1) ...) 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. 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)


File: chicken.info,  Node: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals*,  Prev: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals,  Up: Non-standard macros and special forms - Binding forms for optional arguments

10.2.4 let-optionals*
---------------------


[syntax]  (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)
 Binding constructs for optional procedure arguments. `ARGS' should be
a rest-parameter taken from a lambda-list. `let-optionals' binds `VAR1
...' to available arguments in parallel, or to `DEFAULT1 ...' if not
enough arguments were provided. `let-optionals*' binds `VAR1 ...'
sequentially, so every variable sees the previous ones. If a single
variable `RESTVAR' is given, then it is bound to any remaining
arguments, otherwise it is an error if any excess arguments are
provided.

     (let-optionals* '(one two) ((a 1) (b 2) (c a))
       (list a b c) )                               =*=>* (one two one)


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms,  Next: Non-standard macros and special forms - Substitution forms and macros,  Prev: Non-standard macros and special forms - Binding forms for optional arguments,  Up: Non-standard macros and special forms

10.3 Other binding forms
========================

* Menu:

* Non-standard macros and special forms - Other binding forms - and-let*::
* Non-standard macros and special forms - Other binding forms - rec::
* Non-standard macros and special forms - Other binding forms - cut::
* Non-standard macros and special forms - Other binding forms - define-values::
* Non-standard macros and special forms - Other binding forms - fluid-let::
* Non-standard macros and special forms - Other binding forms - let-values::
* Non-standard macros and special forms - Other binding forms - let*-values::
* Non-standard macros and special forms - Other binding forms - letrec-values::
* Non-standard macros and special forms - Other binding forms - parameterize::
* Non-standard macros and special forms - Other binding forms - receive::
* Non-standard macros and special forms - Other binding forms - set!-values::


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - and-let*,  Next: Non-standard macros and special forms - Other binding forms - rec,  Up: Non-standard macros and special forms - Other binding forms

10.3.1 and-let*
---------------


[syntax] (and-let* (BINDING ...) EXP1 EXP2 ...)
 SRFI-2. Bind sequentially and execute body. `BINDING' can be a list of
a variable and an expression, a list with a single expression, or a
single variable. If the value of an expression bound to a variable is
`#f', the `and-let*' form evaluates to `#f' (and the subsequent
bindings and the body are not executed).  Otherwise the next binding is
performed. If all bindings/expressions evaluate to a true result, the
body is executed normally and the result of the last expression is the
result of the `and-let*' form. See also the documentation for SRFI-2
(http://srfi.schemers.org/srfi-2/srfi-2.html).


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - rec,  Next: Non-standard macros and special forms - Other binding forms - cut,  Prev: Non-standard macros and special forms - Other binding forms - and-let*,  Up: Non-standard macros and special forms - Other binding forms

10.3.2 rec
----------


[syntax] (rec NAME EXPRESSION)
[syntax] (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)'.


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - cut,  Next: Non-standard macros and special forms - Other binding forms - define-values,  Prev: Non-standard macros and special forms - Other binding forms - rec,  Up: Non-standard macros and special forms - Other binding forms

10.3.3 cut
----------


[syntax] (cut SLOT ...)
[syntax] (cute SLOT ...)
 Syntactic sugar for specializing parameters
(http://srfi.schemers.org/srfi-26/srfi-26.html).


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - define-values,  Next: Non-standard macros and special forms - Other binding forms - fluid-let,  Prev: Non-standard macros and special forms - Other binding forms - cut,  Up: Non-standard macros and special forms - Other binding forms

10.3.4 define-values
--------------------


[syntax] (define-values (NAME ...) EXP)
 Defines several variables at once, with the result values of
expression `EXP'.


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - fluid-let,  Next: Non-standard macros and special forms - Other binding forms - let-values,  Prev: Non-standard macros and special forms - Other binding forms - define-values,  Up: Non-standard macros and special forms - Other binding forms

10.3.5 fluid-let
----------------


[syntax] (fluid-let ((VAR1 X1) ...) BODY ...)
 Binds the variables `VAR1 ...' dynamically to the values `X1 ...'
during execution of `BODY ...'.


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - let-values,  Next: Non-standard macros and special forms - Other binding forms - let*-values,  Prev: Non-standard macros and special forms - Other binding forms - fluid-let,  Up: Non-standard macros and special forms - Other binding forms

10.3.6 let-values
-----------------


[syntax] (let-values (((NAME ...) EXP) ...) BODY ...)
 Binds multiple variables to the result values of `EXP ...'. All
variables are bound simultaneously.


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - let*-values,  Next: Non-standard macros and special forms - Other binding forms - letrec-values,  Prev: Non-standard macros and special forms - Other binding forms - let-values,  Up: Non-standard macros and special forms - Other binding forms

10.3.7 let*-values
------------------


[syntax] (let*-values (((NAME ...) EXP) ...) BODY ...)
 Binds multiple variables to the result values of `EXP ...'. The
variables are bound sequentially.

     (let*-values (((a b) (values 2 3))
                   ((p) (+ a b)) )
       p)                               =*=>* 5


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - letrec-values,  Next: Non-standard macros and special forms - Other binding forms - parameterize,  Prev: Non-standard macros and special forms - Other binding forms - let*-values,  Up: Non-standard macros and special forms - Other binding forms

10.3.8 letrec-values
--------------------


[syntax] (letrec-values (((NAME ...) EXP) ...) BODY ...)
 Binds the result values of `EXP ...' to multiple variables at once.
All variables are mutually recursive.

     (letrec-values (((odd even)
                        (values
                          (*lambda* (n) (*if* (zero? n) #f (even (sub1 n))))
                          (*lambda* (n) (*if* (zero? n) #t (odd (sub1 n)))) ) ) )
       (odd 17) )                           =*=>* #t


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - parameterize,  Next: Non-standard macros and special forms - Other binding forms - receive,  Prev: Non-standard macros and special forms - Other binding forms - letrec-values,  Up: Non-standard macros and special forms - Other binding forms

10.3.9 parameterize
-------------------


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


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - receive,  Next: Non-standard macros and special forms - Other binding forms - set!-values,  Prev: Non-standard macros and special forms - Other binding forms - parameterize,  Up: Non-standard macros and special forms - Other binding forms

10.3.10 receive
---------------


[syntax] (receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
[syntax] (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 _)


File: chicken.info,  Node: Non-standard macros and special forms - Other binding forms - set!-values,  Prev: Non-standard macros and special forms - Other binding forms - receive,  Up: Non-standard macros and special forms - Other binding forms

10.3.11 set!-values
-------------------


[syntax] (set!-values (NAME ...) EXP)
 Assigns the result values of expression `EXP' to multiple variables.


File: chicken.info,  Node: Non-standard macros and special forms - Substitution forms and macros,  Next: Non-standard macros and special forms - Conditional forms,  Prev: Non-standard macros and special forms - Other binding forms,  Up: Non-standard macros and special forms

10.4 Substitution forms and macros
==================================

* Menu:

* Non-standard macros and special forms - Substitution forms and macros - define-constant::
* Non-standard macros and special forms - Substitution forms and macros - define-inline::
* Non-standard macros and special forms - Substitution forms and macros - define-macro::
* Non-standard macros and special forms - Substitution forms and macros - define-for-syntax::


File: chicken.info,  Node: Non-standard macros and special forms - Substitution forms and macros - define-constant,  Next: Non-standard macros and special forms - Substitution forms and macros - define-inline,  Up: Non-standard macros and special forms - Substitution forms and macros

10.4.1 define-constant
----------------------


[syntax] (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.


File: chicken.info,  Node: Non-standard macros and special forms - Substitution forms and macros - define-inline,  Next: Non-standard macros and special forms - Substitution forms and macros - define-macro,  Prev: Non-standard macros and special forms - Substitution forms and macros - define-constant,  Up: Non-standard macros and special forms - Substitution forms and macros

10.4.2 define-inline
--------------------


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


File: chicken.info,  Node: Non-standard macros and special forms - Substitution forms and macros - define-macro,  Next: Non-standard macros and special forms - Substitution forms and macros - define-for-syntax,  Prev: Non-standard macros and special forms - Substitution forms and macros - define-inline,  Up: Non-standard macros and special forms - Substitution forms and macros

10.4.3 define-macro
-------------------


[syntax] (define-macro (NAME VAR ... [. VAR]) EXP1 ...)
[syntax] (define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
[syntax] (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.


File: chicken.info,  Node: Non-standard macros and special forms - Substitution forms and macros - define-for-syntax,  Prev: Non-standard macros and special forms - Substitution forms and macros - define-macro,  Up: Non-standard macros and special forms - Substitution forms and macros

10.4.4 define-for-syntax
------------------------


[syntax] (define-for-syntax (NAME VAR ... [. VAR]) EXP1 ...)
[syntax] (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.


File: chicken.info,  Node: Non-standard macros and special forms - Conditional forms,  Next: Non-standard macros and special forms - Record structures,  Prev: Non-standard macros and special forms - Substitution forms and macros,  Up: Non-standard macros and special forms

10.5 Conditional forms
======================

* Menu:

* Non-standard macros and special forms - Conditional forms - select::
* Non-standard macros and special forms - Conditional forms - unless::
* Non-standard macros and special forms - Conditional forms - when::


File: chicken.info,  Node: Non-standard macros and special forms - Conditional forms - select,  Next: Non-standard macros and special forms - Conditional forms - unless,  Up: Non-standard macros and special forms - Conditional forms

10.5.1 select
-------------


[syntax] (select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])
 This is similar to `case', but the keys are evaluated.


File: chicken.info,  Node: Non-standard macros and special forms - Conditional forms - unless,  Next: Non-standard macros and special forms - Conditional forms - when,  Prev: Non-standard macros and special forms - Conditional forms - select,  Up: Non-standard macros and special forms - Conditional forms

10.5.2 unless
-------------


[syntax] (unless TEST EXP1 EXP2 ...)
 Equivalent to:

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


File: chicken.info,  Node: Non-standard macros and special forms - Conditional forms - when,  Prev: Non-standard macros and special forms - Conditional forms - unless,  Up: Non-standard macros and special forms - Conditional forms

10.5.3 when
-----------


[syntax] (when TEST EXP1 EXP2 ...)
 Equivalent to:

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


File: chicken.info,  Node: Non-standard macros and special forms - Record structures,  Next: Non-standard macros and special forms - Other forms,  Prev: Non-standard macros and special forms - Conditional forms,  Up: Non-standard macros and special forms

10.6 Record structures
======================

* Menu:

* Non-standard macros and special forms - Record structures - define-record::
* Non-standard macros and special forms - Record structures - define-record-printer::
* Non-standard macros and special forms - Record structures - define-record-type::


File: chicken.info,  Node: Non-standard macros and special forms - Record structures - define-record,  Next: Non-standard macros and special forms - Record structures - define-record-printer,  Up: Non-standard macros and special forms - Record structures

10.6.1 define-record
--------------------


[syntax] (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


File: chicken.info,  Node: Non-standard macros and special forms - Record structures - define-record-printer,  Next: Non-standard macros and special forms - Record structures - define-record-type,  Prev: Non-standard macros and special forms - Record structures - define-record,  Up: Non-standard macros and special forms - Record structures

10.6.2 define-record-printer
----------------------------


[syntax] (define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)
[syntax] (define-record-printer NAME PROCEDURE)
 Defines a printing method for record of the type `NAME' by associating
a procedure with the record type. When a record of this type is written
using `display, write' or `print', then the procedure is called with
two arguments: the record to be printed and an output-port.

     (define-record foo x y z)
     (*define* *f* (make-foo 1 2 3))
     (define-record-printer (foo x out)
       (fprintf out *"#,(foo ~S ~S ~S)"*
                (foo-x x) (foo-y x) (foo-z x)) )
     (define-reader-ctor 'foo make-foo)
     (*define* *s* (with-output-to-string
                   (*lambda* () (write f))))
     s                                   =*=>* *"#,(foo 1 2 3)"*
     (equal? f (with-input-from-string
                   s read)))             =*=>* #t
`define-record-printer' works also with SRFI-9 record types.


File: chicken.info,  Node: Non-standard macros and special forms - Record structures - define-record-type,  Prev: Non-standard macros and special forms - Record structures - define-record-printer,  Up: Non-standard macros and special forms - Record structures

10.6.3 define-record-type
-------------------------


[syntax] (define-record-type NAME
                             (CONSTRUCTOR TAG ...)
                             PREDICATE
                             (FIELD ACCESSOR [MODIFIER]) ...)
 SRFI-9 record types. For more information see the documentation for
SRFI-9 (http://srfi.schemers.org/srfi-9/srfi-9.html).


File: chicken.info,  Node: Non-standard macros and special forms - Other forms,  Prev: Non-standard macros and special forms - Record structures,  Up: Non-standard macros and special forms

10.7 Other forms
================

* Menu:

* Non-standard macros and special forms - Other forms - assert::
* Non-standard macros and special forms - Other forms - cond-expand::
* Non-standard macros and special forms - Other forms - ensure::
* Non-standard macros and special forms - Other forms - eval-when::
* Non-standard macros and special forms - Other forms - include::
* Non-standard macros and special forms - Other forms - nth-value::
* Non-standard macros and special forms - Other forms - time::


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - assert,  Next: Non-standard macros and special forms - Other forms - cond-expand,  Up: Non-standard macros and special forms - Other forms

10.7.1 assert
-------------


[syntax] (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'.


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - cond-expand,  Next: Non-standard macros and special forms - Other forms - ensure,  Prev: Non-standard macros and special forms - Other forms - assert,  Up: Non-standard macros and special forms - Other forms

10.7.2 cond-expand
------------------


[syntax] (cond-expand FEATURE-CLAUSE ...)
 Expands by selecting feature clauses. This form is allowed to appear
in non-toplevel expressions.

Predefined feature-identifiers are "situation" specific:

compile
     `eval', `library', `match', `compiling', `srfi-11', `srfi-15',
     `srfi-31', `srfi-26', `srfi-16', `utils', `regex', `srfi-4',
     `match', `srfi-1', `srfi-69', `srfi-28', `extras', `srfi-8',
     `srfi-6', `srfi-2', `srfi-0', `srfi-10', `srfi-9', `srfi-55',
     `srfi-61' `chicken', `srfi-23', `srfi-30', `srfi-39', `srfi-62',
     `srfi-17', `srfi-12'.

load
     `srfi-69', `srfi-28', `extras', `srfi-8', `srfi-6', `srfi-2',
     `srfi-0', `srfi-10', `srfi-9', `srfi-55', `srfi-61', `chicken',
     `srfi-23', `srfi-30', `srfi-39', `srfi-62', `srfi-17', `srfi-12'.
     `library' is implicit.

eval
     `match', `csi', `srfi-11', `srfi-15', `srfi-31', `srfi-26',
     `srfi-16', `srfi-69', `srfi-28', `extras', `srfi-8', `srfi-6',
     `srfi-2', `srfi-0', `srfi-10', `srfi-9', `srfi-55', `srfi-61',
     `chicken', `srfi-23', `srfi-30', `srfi-39', `srfi-62', `srfi-17',
     `srfi-12'. `library' is implicit.

   The following feature-identifiers are available in all situations:
`(machine-byte-order)', `(machine-type)', `(software-type)',
`(software-version)', where the actual feature-identifier is platform
dependent.

   In addition the following feature-identifiers may exist:
`applyhook', `extraslot', `ptables', `dload'.

   For further information, see the documentation for SRFI-0
(http://srfi.schemers.org/srfi-0/srfi-0.html).


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - ensure,  Next: Non-standard macros and special forms - Other forms - eval-when,  Prev: Non-standard macros and special forms - Other forms - cond-expand,  Up: Non-standard macros and special forms - Other forms

10.7.3 ensure
-------------


[syntax] (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.


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - eval-when,  Next: Non-standard macros and special forms - Other forms - include,  Prev: Non-standard macros and special forms - Other forms - ensure,  Up: Non-standard macros and special forms - Other forms

10.7.4 eval-when
----------------


[syntax] (eval-when (SITUATION ...) EXP ...)
 Controls evaluation/compilation of subforms. `SITUATION' should be one
of the symbols `eval', `compile' or `load'. When encountered in the
evaluator, and the situation specifier `eval' is not given, then this
form is not evaluated and an unspecified value is returned.  When
encountered 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:

   <table> <tr><th></th><th>In compiled code</th><th>In interpreted
code</th></tr> <tr><td>`eval'</td><td>ignore</td><td>evaluate</td></tr>
<tr><td>`compile'</td><td>evaluate at compile
time</td><td>ignore</td></tr> <tr><td>`load'</td><td>compile as
normal</td><td>ignore</td></tr> </table>

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


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - include,  Next: Non-standard macros and special forms - Other forms - nth-value,  Prev: Non-standard macros and special forms - Other forms - eval-when,  Up: Non-standard macros and special forms - Other forms

10.7.5 include
--------------


[syntax] (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.


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - nth-value,  Next: Non-standard macros and special forms - Other forms - time,  Prev: Non-standard macros and special forms - Other forms - include,  Up: Non-standard macros and special forms - Other forms

10.7.6 nth-value
----------------


[syntax] (nth-value N EXP)
 Returns the `N'th value (counting from zero) of the values returned by
expression `EXP'.


File: chicken.info,  Node: Non-standard macros and special forms - Other forms - time,  Prev: Non-standard macros and special forms - Other forms - nth-value,  Up: Non-standard macros and special forms - Other forms

10.7.7 time
-----------


[syntax] (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.

Previous: *Note Non-standard read syntax: Non-standard read syntax.

   Next: *Note Pattern matching: Pattern matching.


File: chicken.info,  Node: Pattern matching,  Next: Declarations,  Prev: Non-standard macros and special forms,  Up: Top

11 Pattern matching
*******************

* Menu:

* Pattern matching - Pattern Matching Expressions::
* Pattern matching - Patterns::
* Pattern matching - Match Failure::
* Pattern matching - Record Structures Pattern::
* Pattern matching - Code Generation::

   (This description has been taken mostly from Andrew Wright's
postscript document)

   Pattern matching allows complicated control decisions based on data
structure to be expressed in a concise manner.  Pattern matching is
found in several modern languages, notably Standard ML, Haskell and
Miranda. These syntactic extensions internally use the `match' library
unit.

   Note: this pattern matching package is not compatible with hygienic
macro-expanders like the `syntax-case' extension (available separately).

   The basic form of pattern matching expression is:

     (match exp [pat body] ...)
   where `exp' is an expression, `pat' is a pattern, and `body' is one
or more expressions (like the body of a lambda-expression). The `match'
form matches its first subexpression against a sequence of patterns,
and branches to the `body' corresponding to the first pattern
successfully matched. For example, the following code defines the usual
`map' function:

     (*define* *map*
       (*lambda* (f l)
         (match l
           [() '()]
           [(x . y) (cons (f x) (map f y))])))
   The first pattern `()' matches the empty list.  The second pattern
`(x . y)' matches a pair, binding `x' to the first component of the
pair and `y' to the second component of the pair.


File: chicken.info,  Node: Pattern matching - Pattern Matching Expressions,  Next: Pattern matching - Patterns,  Up: Pattern matching

11.1 Pattern Matching Expressions
=================================

The complete syntax of the pattern matching expressions follows:


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
 The notation `..k' denotes a keyword consisting of three consecutive
dots (ie., _`...'_),  or two dots and an non-negative integer (eg.,
_`..1'_, _`..2'_), or three consecutive underscores (ie., _`___'_), or
two underscores and a non-negative integer. The keywords _`..k'_ and
_`__ k'_ are equivalent. The keywords _`...'_, _`___'_, _`..0'_, and
_`__0'_ are equivalent.

   The next subsection describes the various patterns.

   The `match-lambda' and `match-lambda*' forms are convenient
combinations of `match' and `lambda', and can be explained as follows:

     (match-lambda [pat body] ...)   =  (*lambda* (x) (match x [pat body] ...))
     (match-lambda* [pat body] ...)  =  (*lambda* x (match x [pat body] ...))
   where `x' is a unique variable. The `match-lambda' form is
convenient when defining a single argument function that immediately
destructures its argument. The `match-lambda*' form constructs a
function that accepts any number of arguments; the patterns of
`match-lambda*' should be lists.

   The `match-let', `match-let*', `match-letrec', and `match-define'
forms generalize Scheme's `let', `let*', `letrec', and `define'
expressions to allow patterns in the binding position rather than just
variables. For example, the following expression:

     (match-let ([(x y z) (list 1 2 3)]) body ...)
   binds `x' to 1, `y' to 2, and `z' to 3 in `body ...'. These forms
are convenient for destructuring the result of a function that returns
multiple values as a list or vector. As usual for `letrec' and
`define', pattern variables bound by `match-letrec' and `match-define'
should not be used in computing the bound value.

   The `match', `match-lambda', and `match-lambda*' forms allow the
optional syntax `(=> identifier)' between the pattern and the body of a
clause.  When the pattern match for such a clause succeeds, the
`identifier' is bound to a `failure procedure' of zero arguments within
the `body'.  If this procedure is invoked, it jumps back to the pattern
matching expression, and resumes the matching process as if the pattern
had failed to match.  The `body' must not mutate the object being
matched, otherwise unpredictable behavior may result.


File: chicken.info,  Node: Pattern matching - Patterns,  Next: Pattern matching - Match Failure,  Prev: Pattern matching - Pattern Matching Expressions,  Up: Pattern matching

11.2 Patterns
=============

`identifier': (excluding the reserved names `?', `,', `=', `_', `and',
`or', `not', `set!', `get!', `...', and `..k' for non-negative integers
`k') matches anything, and binds a variable of this name to the
matching value in the `body'.

   `_': matches anything, without binding any variables.

   `()', `#t', `#f', `string', `number', `character', '`s-expression':
These constant patterns match themselves, i.e., the corresponding value
must be `equal?' to the pattern.

   `(pat-1 ... pat-n)': matches a proper list of `n' elements that
match `pat-1' through `pat-n'.

   `(pat-1 ... pat-n . pat-n+1)': matches a (possibly improper) list of
at least `n' elements that ends in something matching `pat-n+1'.

   `(pat-1 ... pat-n pat-n+1 ...)': matches a proper list of `n' or
more elements, where each element of the tail matches `pat-n+1'.  Each
pattern variable in `pat-n+1' is bound to a list of the matching
values.  For example, the expression:

     (match '(*let* ([x 1][y 2]) z)
       [('*let* ((binding values) ...) exp)  body])
   binds `binding' to the list `'(x y)', `values' to the list \`'(1
2)', and `exp' to `'z' in the body of the `match'-expression. For the
special case where `pat-n+1' is a pattern variable, the list bound to
that variable may share with the matched value.

   `(pat-1 ... pat-n pat-n+1 ___)': This pattern means the same thing
as the previous pattern.

   `(pat-1 ... pat-n pat-n+1 ..k)': This pattern is similar to the
previous pattern, but the tail must be at least `k' elements long. The
pattern keywords `..0' and `...' are equivalent.

   `(pat-1 ... pat-n ~ pat-n+1 __k)': This pattern means the same thing
as the previous pattern.

   `#(pat-1 ... pat-n)': matches a vector of length `n', whose elements
match `pat-1' through `pat-n'.

   `#(pat-1 ... pat-n pat-n+1 ...)': matches a vector of length `n' or
more, where each element beyond `n' matches `pat-n+1'.

   `#(pat-1 ... pat-n pat-n+1 ..k)': matches a vector of length `n+k'
or more, where each element beyond `n' matches `pat-n+1'.

   `($ struct pat-1 ... pat-n)': matches a structure declared with
`define-record' or `define-record-type'.

   `(= field pat)': is intended for selecting a field from a structure.
_field_ may be any expression; it is applied to the value being
matched, and the result of this application is matched against `pat'.

   `(and pat-1 ... pat-n)': matches if all of the subpatterns match. At
least one subpattern must be present. This pattern is often used as
`(and x pat)' to bind `x' to to the entire value that matches `pat'
(cf. _as-patterns_ in ML or Haskell).

   `(or pat-1 ... pat-n)': matches if any of the subpatterns match. At
least one subpattern must be present. All subpatterns must bind the
same set of pattern variables.

   `(not pat-1 ... pat-n)': matches if none of the subpatterns match.
At least one subpattern must be present. The subpatterns may not bind
any pattern variables.

   `(? predicate pat-1 ... pat-n)': In this pattern, `predicate' must
be an expression evaluating to a single argument function. This pattern
matches if `predicate' applied to the corresponding value is true, and
the subpatterns `pat-1 ... pat-n' all match. The `predicate' should not
have side effects, as the code generated by the pattern matcher may
invoke predicates repeatedly in any order. The `predicate' expression
is bound in the same scope as the match expression, i.e., free
variables in `predicate' are not bound by pattern variables.

   `(set! identifier)': matches anything, and binds `identifier' to a
procedure of one argument that mutates the corresponding field of the
matching value. This pattern must be nested within a pair, vector, box,
or structure pattern. For example, the expression:

     (*define* *x* (list 1 (list 2 3)))
     (match x [(_ (_ (*set!* setit)))  (setit 4)])
   mutates the `cadadr' of `x' to 4, so that `x' is `'(1 (2 4))'.

   `(get! identifier)': matches anything, and binds `identifier' to a
procedure of zero arguments that accesses the corresponding field of
the matching value.  This pattern is the complement to `set!'. As with
`set!', this pattern must be nested within a pair, vector, box, or
structure pattern.

   _Quasipatterns_: Quasiquote introduces a quasipattern, in which
identifiers are considered to be symbolic constants.  Like Scheme's
quasiquote for data, `unquote' (,) and `unquote-splicing' (,@) escape
back to normal patterns.


File: chicken.info,  Node: Pattern matching - Match Failure,  Next: Pattern matching - Record Structures Pattern,  Prev: Pattern matching - Patterns,  Up: Pattern matching

11.3 Match Failure
==================

If no clause matches the value, the default action  is to invoke the
procedure `(match-error-procedure)' with the value that did not match.
The default definition of `(match-error-procedure)' calls `error' with
an appropriate message:

     #_;1> (match 1 (2 2))
     _
     Failed match:
     Error: no matching clause for *:* 1
   For most situations, this behavior is adequate, but it can be
changed by altering the value of the parameter `match-error-control':

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

   <table>

   <tr> <td>#:error</td> <td>

   Signal an error. This is the default.

   </td> </tr>

   <tr> <td>#:match</td> <td>

   Signal an error and output the offending form.

   </td> </tr>

   <tr> <td>#:fail</td> <td>

   Omits `pair?' tests when the consequence is to fail in `car' or
`cdr' rather than to signal an error.

   </td> </tr>

   <tr> <td>unspecified</td> <td>

   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.

   </td> </tr>

   </table>

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

[procedure] match-error-procedure

     (match-error-procedure [PROCEDURE])
   Sets or returns the procedure called upon a match error. The
procedure takes one argument, the value which failed to match. When the
error control mode is `#:match' a second argument, the source form of
the match expression is available.


File: chicken.info,  Node: Pattern matching - Record Structures Pattern,  Next: Pattern matching - Code Generation,  Prev: Pattern matching - Match Failure,  Up: Pattern matching

11.4 Record Structures Pattern
==============================

The `$' pattern handles native record structures and SRFI-9
(http://srfi.schemers.org/srfi-9/srfi-9.html) records transparently.
Currently it is required that SRFI-9
(http://srfi.schemers.org/srfi-9/srfi-9.html) record predicates are
named exactly like the record type name, followed by a `?' (question
mark) character.


File: chicken.info,  Node: Pattern matching - Code Generation,  Prev: Pattern matching - Record Structures Pattern,  Up: Pattern matching

11.5 Code Generation
====================

Pattern matching macros are compiled into `if'-expressions that
decompose the value being matched with standard Scheme procedures, and
test the components with standard predicates. Rebinding or lexically
shadowing the names of any of these procedures will change the
semantics of the `match' macros.  The names that should not be rebound
or shadowed are:

     null? pair? number? string? symbol? boolean? char? procedure? vector? list?
     equal?
     car cdr cadr cdddr ...
     vector-length vector-ref
     reverse length call/cc
   Additionally, the code generated to match a structure pattern like
`($ Foo pat-1 ... pat-n)' refers to the name `Foo?'. This name also
should not be shadowed.

   Previous: *Note Non-standard macros and special forms: Non-standard
macros and special forms.

   Next: *Note Declarations: Declarations.


File: chicken.info,  Node: Declarations,  Next: Parameters,  Prev: Pattern matching,  Up: Top

12 Declarations
***************

* Menu:

* Declarations - declare::
* Declarations - always-bound::
* Declarations - block::
* Declarations - block-global::
* Declarations - hide::
* Declarations - bound-to-procedure::
* Declarations - c-options::
* Declarations - check-c-syntax::
* Declarations - constant::
* Declarations - export::
* Declarations - emit-exports::
* Declarations - emit-external-prototypes-first::
* Declarations - disable-interrupts::
* Declarations - disable-warning::
* Declarations - import::
* Declarations - inline::
* Declarations - inline-limit::
* Declarations - interrupts-enabled::
* Declarations - keep-shadowed-macros::
* Declarations - lambda-lift::
* Declarations - link-options::
* Declarations - no-argc-checks::
* Declarations - no-bound-checks::
* Declarations - no-procedure-checks::
* Declarations - post-process::
* Declarations - profile::
* Declarations - number-type::
* Declarations - fixnum-arithmetic::
* Declarations - run-time-macros::
* Declarations - standard-bindings::
* Declarations - extended-bindings::
* Declarations - usual-integrations::
* Declarations - unit::
* Declarations - unsafe::
* Declarations - unused::
* Declarations - uses::


File: chicken.info,  Node: Declarations - declare,  Next: Declarations - always-bound,  Up: Declarations

12.1 declare
============


[syntax] (declare DECLSPEC ...)
 Process declaration specifiers. Declarations always override any
command-line settings.  Declarations are valid for the whole
compilation-unit (source file), the position of the declaration in the
source file can be arbitrary. 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:


File: chicken.info,  Node: Declarations - always-bound,  Next: Declarations - block,  Prev: Declarations - declare,  Up: Declarations

12.2 always-bound
=================


[declaration specifier] (always-bound SYMBOL ...)
 Declares that the given variables are always bound and accesses to
those have not to be checked.


File: chicken.info,  Node: Declarations - block,  Next: Declarations - block-global,  Prev: Declarations - always-bound,  Up: Declarations

12.3 block
==========


[declaration specifier] (block)
 Assume global variables are never redefined. This is the same as
specifying the `-block' option.


File: chicken.info,  Node: Declarations - block-global,  Next: Declarations - hide,  Prev: Declarations - block,  Up: Declarations

12.4 block-global
=================


File: chicken.info,  Node: Declarations - hide,  Next: Declarations - bound-to-procedure,  Prev: Declarations - block-global,  Up: Declarations

12.5 hide
=========


[declaration specifier] (block-global SYMBOL ...)
[declaration specifier] (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.


File: chicken.info,  Node: Declarations - bound-to-procedure,  Next: Declarations - c-options,  Prev: Declarations - hide,  Up: Declarations

12.6 bound-to-procedure
=======================


[declaration specifier] (bound-to-procedure SYMBOL ...)
 Declares that the given identifiers are always bound to procedure
values.


File: chicken.info,  Node: Declarations - c-options,  Next: Declarations - check-c-syntax,  Prev: Declarations - bound-to-procedure,  Up: Declarations

12.7 c-options
==============


[declaration specifier] (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.


File: chicken.info,  Node: Declarations - check-c-syntax,  Next: Declarations - constant,  Prev: Declarations - c-options,  Up: Declarations

12.8 check-c-syntax
===================


[declaration specifier] (check-c-syntax)
[declaration specifier] (not check-c-syntax)
 Enables or disables syntax-checking of embedded C/C++ code fragments.
Checking C syntax is the default.


File: chicken.info,  Node: Declarations - constant,  Next: Declarations - export,  Prev: Declarations - check-c-syntax,  Up: Declarations

12.9 constant
=============


[declaration specifier] (constant SYMBOL ...)
 Declares the procedures with the names `SYMBOL ...' as constant, that
is, as not having any side effects. This can help the compiler to
remove non-side-effecting expressions.


File: chicken.info,  Node: Declarations - export,  Next: Declarations - emit-exports,  Prev: Declarations - constant,  Up: Declarations

12.10 export
============


[declaration specifier] (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.


File: chicken.info,  Node: Declarations - emit-exports,  Next: Declarations - emit-external-prototypes-first,  Prev: Declarations - export,  Up: Declarations

12.11 emit-exports
==================


[declaration specifier] (emit-exports STRING)
 Write exported toplevel variables to file with name `STRING'.


File: chicken.info,  Node: Declarations - emit-external-prototypes-first,  Next: Declarations - disable-interrupts,  Prev: Declarations - emit-exports,  Up: Declarations

12.12 emit-external-prototypes-first
====================================


[declaration specifier] (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.


File: chicken.info,  Node: Declarations - disable-interrupts,  Next: Declarations - disable-warning,  Prev: Declarations - emit-external-prototypes-first,  Up: Declarations

12.13 disable-interrupts
========================


[declaration specifier] (disable-interrupts)
[declaration specifier] (not interrupts-enabled)
 Disable timer-interrupts checks in the compiled program. Threads can
not be preempted in main- or library-units that contain this
declaration.


File: chicken.info,  Node: Declarations - disable-warning,  Next: Declarations - import,  Prev: Declarations - disable-interrupts,  Up: Declarations

12.14 disable-warning
=====================


[declaration specifier] (disable-warning CLASS ...)
 Disable warnings of type `CLASS ...' (equivalent to the
`-disable-warning CLASS' compiler option).


File: chicken.info,  Node: Declarations - import,  Next: Declarations - inline,  Prev: Declarations - disable-warning,  Up: Declarations

12.15 import
============


[declaration specifier] (import SYMBOL-OR-STRING ...)
 Adds new imports to the list of externally available toplevel
variables. Arguments to this declaration may be either strings
(designating `.exports' files, without the file-extension) or symbols
which directly designate imported variables.


File: chicken.info,  Node: Declarations - inline,  Next: Declarations - inline-limit,  Prev: Declarations - import,  Up: Declarations

12.16 inline
============


[declaration specifier] (inline)
[declaration specifier] (not inline)
[declaration specifier] (inline IDENTIFIER ...)
[declaration specifier] (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.


File: chicken.info,  Node: Declarations - inline-limit,  Next: Declarations - interrupts-enabled,  Prev: Declarations - inline,  Up: Declarations

12.17 inline-limit
==================


[declaration specifier] (inline-limit THRESHOLD)
 Sets the maximum size of procedures which may potentially be inlined.
The default threshold is `10'.


File: chicken.info,  Node: Declarations - interrupts-enabled,  Next: Declarations - keep-shadowed-macros,  Prev: Declarations - inline-limit,  Up: Declarations

12.18 interrupts-enabled
========================


[declaration specifier] (interrupts-enabled)
 Enable timer-interrupts checks in the compiled program (the default).


File: chicken.info,  Node: Declarations - keep-shadowed-macros,  Next: Declarations - lambda-lift,  Prev: Declarations - interrupts-enabled,  Up: Declarations

12.19 keep-shadowed-macros
==========================


[declaration specifier] (keep-shadowed-macros)
 Normally, when a toplevel variable is assigned or defined that has the
same name as a macro, the macro-definition will be removed (in addition
to showing a warning). This declaration will disable the removal of the
macro.


File: chicken.info,  Node: Declarations - lambda-lift,  Next: Declarations - link-options,  Prev: Declarations - keep-shadowed-macros,  Up: Declarations

12.20 lambda-lift
=================


[declaration specifier] (lambda-lift)
 Enables lambda-lifting (equivalent to the `-lambda-lift' option).


File: chicken.info,  Node: Declarations - link-options,  Next: Declarations - no-argc-checks,  Prev: Declarations - lambda-lift,  Up: Declarations

12.21 link-options
==================


[declaration specifier] (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.


File: chicken.info,  Node: Declarations - no-argc-checks,  Next: Declarations - no-bound-checks,  Prev: Declarations - link-options,  Up: Declarations

12.22 no-argc-checks
====================


[declaration specifier] (no-argc-checks)
 Disables argument count checking.


File: chicken.info,  Node: Declarations - no-bound-checks,  Next: Declarations - no-procedure-checks,  Prev: Declarations - no-argc-checks,  Up: Declarations

12.23 no-bound-checks
=====================


[declaration specifier] (no-bound-checks)
 Disables the bound-checking of toplevel bindings.


File: chicken.info,  Node: Declarations - no-procedure-checks,  Next: Declarations - post-process,  Prev: Declarations - no-bound-checks,  Up: Declarations

12.24 no-procedure-checks
=========================


[declaration specifier] (no-procedure-checks)
 Disables checking of values in operator position for being of
procedure type.


File: chicken.info,  Node: Declarations - post-process,  Next: Declarations - profile,  Prev: Declarations - no-procedure-checks,  Up: Declarations

12.25 post-process
==================


[declaration specifier] (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.


File: chicken.info,  Node: Declarations - profile,  Next: Declarations - number-type,  Prev: Declarations - post-process,  Up: Declarations

12.26 profile
=============


[declaration specifier] (profile IDENTIFIER ...)
 Enable profiling exclusively for given identifiers. Normally the
compiler enables profiling decorations for all globally defined
procedures. With this declaration, profiling can be enabled for
selected procedures.


File: chicken.info,  Node: Declarations - number-type,  Next: Declarations - fixnum-arithmetic,  Prev: Declarations - profile,  Up: Declarations

12.27 number-type
=================


File: chicken.info,  Node: Declarations - fixnum-arithmetic,  Next: Declarations - run-time-macros,  Prev: Declarations - number-type,  Up: Declarations

12.28 fixnum-arithmetic
=======================


[declaration specifier] ([number-type] TYPE)
[declaration specifier] (fixnum-arithmetic)
 Declares that only numbers of the given type are used. `TYPE' may be
`fixnum' or `generic' (which is the default).


File: chicken.info,  Node: Declarations - run-time-macros,  Next: Declarations - standard-bindings,  Prev: Declarations - fixnum-arithmetic,  Up: Declarations

12.29 run-time-macros
=====================


[declaration specifier] (run-time-macros)
 Equivalent to the compiler option of the same name - macros defined in
the compiled code are also made available at runtime.


File: chicken.info,  Node: Declarations - standard-bindings,  Next: Declarations - extended-bindings,  Prev: Declarations - run-time-macros,  Up: Declarations

12.30 standard-bindings
=======================


[declaration specifier] (standard-bindings SYMBOL ...)
[declaration specifier] (not standard-bindings SYMBOL ...)
 Declares that all given standard procedures (or all if no symbols are
specified) are never globally redefined.  If `not' is specified, then
all but the given standard bindings are assumed to be never redefined.


File: chicken.info,  Node: Declarations - extended-bindings,  Next: Declarations - usual-integrations,  Prev: Declarations - standard-bindings,  Up: Declarations

12.31 extended-bindings
=======================


[declaration specifier] (extended-bindings SYMBOL ...)
[declaration specifier] (not extended-bindings SYMBOL ...)
 Declares that all given non-standard and CHICKEN-specific procedures
(or all if no symbols are specified) are never globally redefined. If
`not' is specified, then all but the given extended bindings are
assumed to be never redefined.


File: chicken.info,  Node: Declarations - usual-integrations,  Next: Declarations - unit,  Prev: Declarations - extended-bindings,  Up: Declarations

12.32 usual-integrations
========================


[declaration specifier] (usual-integrations SYMBOL ...)
[declaration specifier] (not usual-integrations SYMBOL ...)
 Declares that all given standard and extended bindings (or all if no
symbols are specified) are never globally redefined.  If `not' is
specified, then all but the given standard and extended bindings are
assumed to be never redefined. Note that this is the default behaviour,
unless the `-no-usual-integrations' option has been given.


File: chicken.info,  Node: Declarations - unit,  Next: Declarations - unsafe,  Prev: Declarations - usual-integrations,  Up: Declarations

12.33 unit
==========


[declaration specifier] (unit SYMBOL)
 Specify compilation unit-name (if this is a library)


File: chicken.info,  Node: Declarations - unsafe,  Next: Declarations - unused,  Prev: Declarations - unit,  Up: Declarations

12.34 unsafe
============


[declaration specifier] (unsafe)
[declaration specifier] (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))


File: chicken.info,  Node: Declarations - unused,  Next: Declarations - uses,  Prev: Declarations - unsafe,  Up: Declarations

12.35 unused
============


[declaration specifier] (unused SYMBOL ...)
 Disables any warnings when the global variable `SYMBOL' is not defined
but used,  or defined but never used and not exported.


File: chicken.info,  Node: Declarations - uses,  Prev: Declarations - unused,  Up: Declarations

12.36 uses
==========


[declaration specifier] (uses SYMBOL ...)
 Gives a list of used library-units. Before the toplevel-expressions of
the main-module are executed, all used units evaluate their
toplevel-expressions in the order in which they appear in this
declaration. If a library unit A uses another unit B, then B's toplevel
expressions are evaluated before A's.  Furthermore, the used symbols
are registered as features during compile-time, so `cond-expand' knows
about them.

Previous: *Note Pattern matching: Pattern matching.

   Next: *Note Parameters: Parameters.


File: chicken.info,  Node: Parameters,  Next: Unit library,  Prev: Declarations,  Up: Top

13 Parameters
*************

* Menu:

* Parameters - make-parameter::
* Parameters - case-sensitive::
* Parameters - dynamic-load-libraries::
* Parameters - command-line-arguments::
* Parameters - current-read-table::
* Parameters - exit-handler::
* Parameters - eval-handler::
* Parameters - force-finalizers::
* Parameters - implicit-exit-handler::
* Parameters - keyword-style::
* Parameters - load-verbose::
* Parameters - program-name::
* Parameters - repl-prompt::
* Parameters - reset-handler::

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

     (*define* *foo* (make-parameter 123))
     (foo)                             =*=>* 123
     (foo 99)
     (foo)                             =*=>* 99
   Parameters are fully thread-local, each thread of execution owns a
local copy of a parameters' value.

   CHICKEN implements SRFI-39
(http://srfi.schemers.org/srfi-39/srfi-39.html).


File: chicken.info,  Node: Parameters - make-parameter,  Next: Parameters - case-sensitive,  Up: Parameters

13.1 make-parameter
===================


[procedure] (make-parameter VALUE [GUARD])
 Returns a procedure that accepts zero or one argument. Invoking the
procedure with zero arguments returns `VALUE'. Invoking the procedure
with one argument changes 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.


File: chicken.info,  Node: Parameters - case-sensitive,  Next: Parameters - dynamic-load-libraries,  Prev: Parameters - make-parameter,  Up: Parameters

13.2 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'.


File: chicken.info,  Node: Parameters - dynamic-load-libraries,  Next: Parameters - command-line-arguments,  Prev: Parameters - case-sensitive,  Up: Parameters

13.3 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'.


File: chicken.info,  Node: Parameters - command-line-arguments,  Next: Parameters - current-read-table,  Prev: Parameters - dynamic-load-libraries,  Up: Parameters

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


File: chicken.info,  Node: Parameters - current-read-table,  Next: Parameters - exit-handler,  Prev: Parameters - command-line-arguments,  Up: Parameters

13.5 current-read-table
=======================

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


File: chicken.info,  Node: Parameters - exit-handler,  Next: Parameters - eval-handler,  Prev: Parameters - current-read-table,  Up: Parameters

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


File: chicken.info,  Node: Parameters - eval-handler,  Next: Parameters - force-finalizers,  Prev: Parameters - exit-handler,  Up: Parameters

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


File: chicken.info,  Node: Parameters - force-finalizers,  Next: Parameters - implicit-exit-handler,  Prev: Parameters - eval-handler,  Up: Parameters

13.8 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'.


File: chicken.info,  Node: Parameters - implicit-exit-handler,  Next: Parameters - keyword-style,  Prev: Parameters - force-finalizers,  Up: Parameters

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


File: chicken.info,  Node: Parameters - keyword-style,  Next: Parameters - load-verbose,  Prev: Parameters - implicit-exit-handler,  Up: Parameters

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


File: chicken.info,  Node: Parameters - load-verbose,  Next: Parameters - program-name,  Prev: Parameters - keyword-style,  Up: Parameters

13.11 load-verbose
==================

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


File: chicken.info,  Node: Parameters - program-name,  Next: Parameters - repl-prompt,  Prev: Parameters - load-verbose,  Up: Parameters

13.12 program-name
==================

The name of the currently executing program. This is equivalent to
`(car (argv))' for compiled programs or the filename following the
`-script' option in interpreted scripts.


File: chicken.info,  Node: Parameters - repl-prompt,  Next: Parameters - reset-handler,  Prev: Parameters - program-name,  Up: Parameters

13.13 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> ")'.


File: chicken.info,  Node: Parameters - reset-handler,  Prev: Parameters - repl-prompt,  Up: Parameters

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

   Previous: *Note Declarations: Declarations.

   Next: *Note Unit library: Unit library.


File: chicken.info,  Node: Unit library,  Next: Unit eval,  Prev: Parameters,  Up: Top

14 Unit library
***************

* Menu:

* Unit library - Arithmetic::
* Unit library - File Input/Output::
* Unit library - Files::
* Unit library - String ports::
* Unit library - Feature identifiers::
* Unit library - Keywords::
* Unit library - Exceptions::
* Unit library - Environment information and system interface::
* Unit library - Execution time::
* Unit library - Interrupts and error-handling::
* Unit library - Garbage collection::
* Unit library - Other control structures::
* Unit library - String utilities::
* Unit library - Generating uninterned symbols::
* Unit library - Standard Input/Output::
* Unit library - User-defined named characters::
* Unit library - Blobs::
* Unit library - Vectors::
* Unit library - The unspecified value::
* Unit library - Continuations::
* Unit library - Setters::
* Unit library - Reader extensions::
* Unit library - Property lists::

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


File: chicken.info,  Node: Unit library - Arithmetic,  Next: Unit library - File Input/Output,  Up: Unit library

14.1 Arithmetic
===============

* Menu:

* Unit library - Arithmetic - add1/sub1::
* Unit library - Arithmetic - Binary integer operations::
* Unit library - Arithmetic - bit-set?::
* Unit library - Arithmetic - fixnum?::
* Unit library - Arithmetic - Arithmetic fixnum operations::
* Unit library - Arithmetic - Arithmetic floating-point operations::
* Unit library - Arithmetic - signum::
* Unit library - Arithmetic - finite?::


File: chicken.info,  Node: Unit library - Arithmetic - add1/sub1,  Next: Unit library - Arithmetic - Binary integer operations,  Up: Unit library - Arithmetic

14.1.1 add1/sub1
----------------

[procedure] (add1 N)

[procedure] (sub1 N)
Adds/subtracts 1 from `N'.


File: chicken.info,  Node: Unit library - Arithmetic - Binary integer operations,  Next: Unit library - Arithmetic - bit-set?,  Prev: Unit library - Arithmetic - add1/sub1,  Up: Unit library - Arithmetic

14.1.2 Binary integer operations
--------------------------------

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] (bitwise-and N1 ...)

[procedure] (bitwise-ior N1 ...)

[procedure] (bitwise-xor N1 ...)

[procedure] (bitwise-not N)

[procedure] (arithmetic-shift N1 N2)


File: chicken.info,  Node: Unit library - Arithmetic - bit-set?,  Next: Unit library - Arithmetic - fixnum?,  Prev: Unit library - Arithmetic - Binary integer operations,  Up: Unit library - Arithmetic

14.1.3 bit-set?
---------------


[procedure] (bit-set? N INDEX)
 Returns `#t' if the bit at the position `INDEX' in the integer `N' is
set, or `#f' otherwise. The rightmost/least-significant bit is bit 0.


File: chicken.info,  Node: Unit library - Arithmetic - fixnum?,  Next: Unit library - Arithmetic - Arithmetic fixnum operations,  Prev: Unit library - Arithmetic - bit-set?,  Up: Unit library - Arithmetic

14.1.4 fixnum?
--------------


[procedure] (fixnum? X)
 Returns `#t' if `X' is a fixnum, or `#f' otherwise.


File: chicken.info,  Node: Unit library - Arithmetic - Arithmetic fixnum operations,  Next: Unit library - Arithmetic - Arithmetic floating-point operations,  Prev: Unit library - Arithmetic - fixnum?,  Up: Unit library - Arithmetic

14.1.5 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] (fx+ N1 N2)

[procedure] (fx- N1 N2)

[procedure] (fx* N1 N2)

[procedure] (fx/ N1 N2)

[procedure] (fxmod N1 N2)

[procedure] (fxneg N)

[procedure] (fxmin N1 N2)

[procedure] (fxmax N1 N2)

[procedure] (fx= N1 N2)

[procedure] (fx> N1 N2)

[procedure] (fx< N1 N2)

[procedure] (fx>= N1 N2)

[procedure] (fx<= N1 N2)

[procedure] (fxand N1 N2)

[procedure] (fxior N1 N2)

[procedure] (fxxor N1 N2)

[procedure] (fxnot N)

[procedure] (fxshl N1 N2)

[procedure] (fxshr N1 N2)


File: chicken.info,  Node: Unit library - Arithmetic - Arithmetic floating-point operations,  Next: Unit library - Arithmetic - signum,  Prev: Unit library - Arithmetic - Arithmetic fixnum operations,  Up: Unit library - Arithmetic

14.1.6 Arithmetic floating-point operations
-------------------------------------------

In safe mode, these procedures throw a type error with non-float
arguments (except `flonum?', which returns `#f'). In unsafe mode, these
procedures do not check their arguments. A non-flonum argument in
unsafe mode can crash the system.

[procedure] (flonum? X)

[procedure] (fp+ X Y)

[procedure] (fp- X Y)

[procedure] (fp* X Y)

[procedure] (fp/ X Y)

[procedure] (fpneg X)

[procedure] (fpmin X Y)

[procedure] (fpmax X Y)

[procedure] (fp= X Y)

[procedure] (fp> X Y)

[procedure] (fp< X Y)

[procedure] (fp>= X Y)

[procedure] (fp<= X Y)


File: chicken.info,  Node: Unit library - Arithmetic - signum,  Next: Unit library - Arithmetic - finite?,  Prev: Unit library - Arithmetic - Arithmetic floating-point operations,  Up: Unit library - Arithmetic

14.1.7 signum
-------------


[procedure] (signum N)
 Returns `1' if `N' is positive, `-1' if `N' is negative or `0' if `N'
is zero. `signum' is exactness preserving.


File: chicken.info,  Node: Unit library - Arithmetic - finite?,  Prev: Unit library - Arithmetic - signum,  Up: Unit library - Arithmetic

14.1.8 finite?
--------------


[procedure] (finite? N)
 Returns `#f' if `N' is negative or positive infinity, and `#t'
otherwise.


File: chicken.info,  Node: Unit library - File Input/Output,  Next: Unit library - Files,  Prev: Unit library - Arithmetic,  Up: Unit library

14.2 File Input/Output
======================

* Menu:

* Unit library - File Input/Output - current-output-port::
* Unit library - File Input/Output - current-error-port::
* Unit library - File Input/Output - flush-output::
* Unit library - File Input/Output - port-name::
* Unit library - File Input/Output - port-position::
* Unit library - File Input/Output - set-port-name!::


File: chicken.info,  Node: Unit library - File Input/Output - current-output-port,  Next: Unit library - File Input/Output - current-error-port,  Up: Unit library - File Input/Output

14.2.1 current-output-port
--------------------------


[procedure] (current-output-port [PORT])
 Returns default output port. If `PORT' is given, then that port is
selected as the new current output port.

Note that the default output port is not buffered. Use [[Unit
posix#Setting the file buffering mode|`set-buffering-mode!']] if you
need a different behavior.


File: chicken.info,  Node: Unit library - File Input/Output - current-error-port,  Next: Unit library - File Input/Output - flush-output,  Prev: Unit library - File Input/Output - current-output-port,  Up: Unit library - File Input/Output

14.2.2 current-error-port
-------------------------


[procedure] (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.

Note that the default error output port is not buffered. Use [[Unit
posix#Setting the file buffering mode|`set-buffering-mode!']] if you
need a different behavior.


File: chicken.info,  Node: Unit library - File Input/Output - flush-output,  Next: Unit library - File Input/Output - port-name,  Prev: Unit library - File Input/Output - current-error-port,  Up: Unit library - File Input/Output

14.2.3 flush-output
-------------------


[procedure] (flush-output [PORT])
 Write buffered output to the given output-port. `PORT' defaults to the
value of `(current-output-port)'.


File: chicken.info,  Node: Unit library - File Input/Output - port-name,  Next: Unit library - File Input/Output - port-position,  Prev: Unit library - File Input/Output - flush-output,  Up: Unit library - File Input/Output

14.2.4 port-name
----------------


[procedure] (port-name [PORT])
 Fetch filename from `PORT'. This returns the filename that was used to
open this file. Returns a special tag string, enclosed into parentheses
for non-file ports. `PORT' defaults to the value of
`(current-input-port)'.


File: chicken.info,  Node: Unit library - File Input/Output - port-position,  Next: Unit library - File Input/Output - set-port-name!,  Prev: Unit library - File Input/Output - port-name,  Up: Unit library - File Input/Output

14.2.5 port-position
--------------------


[procedure] (port-position [PORT])
 Returns the current position of `PORT' as two values: row and column
number.  If the port does not support such an operation an error is
signaled. This procedure is currently only available for input ports.
`PORT' defaults to the value of `(current-input-port)'.


File: chicken.info,  Node: Unit library - File Input/Output - set-port-name!,  Prev: Unit library - File Input/Output - port-position,  Up: Unit library - File Input/Output

14.2.6 set-port-name!
---------------------


[procedure] (set-port-name! PORT STRING)
 Sets the name of `PORT' to `STRING'.


File: chicken.info,  Node: Unit library - Files,  Next: Unit library - String ports,  Prev: Unit library - File Input/Output,  Up: Unit library

14.3 Files
==========

* Menu:

* Unit library - Files - delete-file::
* Unit library - Files - file-exists?::
* Unit library - Files - rename-file::


File: chicken.info,  Node: Unit library - Files - delete-file,  Next: Unit library - Files - file-exists?,  Up: Unit library - Files

14.3.1 delete-file
------------------


[procedure] (delete-file STRING)
 Deletes the file with the pathname `STRING'. If the file does not
exist, an error is signaled.


File: chicken.info,  Node: Unit library - Files - file-exists?,  Next: Unit library - Files - rename-file,  Prev: Unit library - Files - delete-file,  Up: Unit library - Files

14.3.2 file-exists?
-------------------


[procedure] (file-exists? STRING)
 Returns `STRING' if a file with the given pathname exists, or `#f'
otherwise.


File: chicken.info,  Node: Unit library - Files - rename-file,  Prev: Unit library - Files - file-exists?,  Up: Unit library - Files

14.3.3 rename-file
------------------


[procedure] (rename-file OLD NEW)
 Renames the file or directory with the pathname `OLD' to `NEW'. If the
operation does not succeed, an error is signaled.


File: chicken.info,  Node: Unit library - String ports,  Next: Unit library - Feature identifiers,  Prev: Unit library - Files,  Up: Unit library

14.4 String ports
=================

* Menu:

* Unit library - String ports - get-output-string::
* Unit library - String ports - open-input-string::
* Unit library - String ports - open-output-string::


File: chicken.info,  Node: Unit library - String ports - get-output-string,  Next: Unit library - String ports - open-input-string,  Up: Unit library - String ports

14.4.1 get-output-string
------------------------


[procedure] (get-output-string PORT)
 Returns accumulated output of a port created with
`(open-output-string)'.


File: chicken.info,  Node: Unit library - String ports - open-input-string,  Next: Unit library - String ports - open-output-string,  Prev: Unit library - String ports - get-output-string,  Up: Unit library - String ports

14.4.2 open-input-string
------------------------


[procedure] (open-input-string STRING)
 Returns a port for reading from `STRING'.


File: chicken.info,  Node: Unit library - String ports - open-output-string,  Prev: Unit library - String ports - open-input-string,  Up: Unit library - String ports

14.4.3 open-output-string
-------------------------


[procedure] (open-output-string)
 Returns a port for accumulating output in a string.


File: chicken.info,  Node: Unit library - Feature identifiers,  Next: Unit library - Keywords,  Prev: Unit library - String ports,  Up: Unit library

14.5 Feature identifiers
========================

* Menu:

* Unit library - Feature identifiers - features::
* Unit library - Feature identifiers - feature?::
* Unit library - Feature identifiers - register-feature!::
* Unit library - Feature identifiers - unregister-feature!::

   CHICKEN maintains a global list of _features_ naming functionality
available in the current system. Additionally the `cond-expand' form
accesses this feature list to infer what features are provided.
Predefined features are `chicken', and the SRFIs (Scheme Request For
Implementation) provided by the base system: `srfi-23, srfi-30,
srfi-39'. If the `eval' unit is used (the default), the features
`srfi-0, srfi-2, srfi-6, srfi-8, srfi-9' and `srfi-10' are defined.
When compiling code (during compile-time) the feature `compiling' is
registered. When evaluating code in the interpreter (csi), the feature
`csi' is registered.


File: chicken.info,  Node: Unit library - Feature identifiers - features,  Next: Unit library - Feature identifiers - feature?,  Up: Unit library - Feature identifiers

14.5.1 features
---------------


[procedure] (features)
 Returns a list of all registered features that will be accepted as
valid feature-identifiers by `cond-expand'.


File: chicken.info,  Node: Unit library - Feature identifiers - feature?,  Next: Unit library - Feature identifiers - register-feature!,  Prev: Unit library - Feature identifiers - features,  Up: Unit library - Feature identifiers

14.5.2 feature?
---------------


[procedure] (feature? ID ...)
 Returns `#t' if all features with the given feature-identifiers `ID
...' are registered.


File: chicken.info,  Node: Unit library - Feature identifiers - register-feature!,  Next: Unit library - Feature identifiers - unregister-feature!,  Prev: Unit library - Feature identifiers - feature?,  Up: Unit library - Feature identifiers

14.5.3 register-feature!
------------------------


[procedure] (register-feature! FEATURE ...)
 Register one or more features that will be accepted as valid
feature-identifiers by `cond-expand'. `FEATURE ...' may be a keyword,
string or symbol.


File: chicken.info,  Node: Unit library - Feature identifiers - unregister-feature!,  Prev: Unit library - Feature identifiers - register-feature!,  Up: Unit library - Feature identifiers

14.5.4 unregister-feature!
--------------------------


[procedure] (unregister-feature! FEATURE ...)
 Unregisters the specified feature-identifiers. `FEATURE ...' may be a
keyword, string or symbol.


File: chicken.info,  Node: Unit library - Keywords,  Next: Unit library - Exceptions,  Prev: Unit library - Feature identifiers,  Up: Unit library

14.6 Keywords
=============

* Menu:

* Unit library - Keywords - get-keyword::
* Unit library - Keywords - keyword?::
* Unit library - Keywords - keyword->string::
* Unit library - Keywords - string->keyword::

   Keywords are special symbols prefixed with `#:' that evaluate to
themselves. Procedures can use keywords to accept optional named
parameters in addition to normal required parameters. Assignment to and
bindings of keyword symbols is not allowed. The parameter
`keyword-style' and the compiler/interpreter option `-keyword-style'
can be used to allow an additional keyword syntax, either compatible to
Common LISP, or to DSSSL.


File: chicken.info,  Node: Unit library - Keywords - get-keyword,  Next: Unit library - Keywords - keyword?,  Up: Unit library - Keywords

14.6.1 get-keyword
------------------


[procedure] (get-keyword KEYWORD ARGLIST [THUNK])
 Returns the argument from `ARGLIST' specified under the keyword
`KEYWORD'. If the keyword is not found, then the zero-argument
procedure `THUNK' is invoked and the result value is returned. If
`THUNK' is not given, `#f' is returned.

     (*define* (*increase* x . args)
       (+ x (get-keyword #:amount args (*lambda* () 1))) )
     (increase 123)                                      =*=>* 124
     (increase 123 #:amount 10)                          =*=>* 133
Note: the `KEYWORD' may actually be any kind of object.


File: chicken.info,  Node: Unit library - Keywords - keyword?,  Next: Unit library - Keywords - keyword->string,  Prev: Unit library - Keywords - get-keyword,  Up: Unit library - Keywords

14.6.2 keyword?
---------------


[procedure] (keyword? X)
 Returns `#t' if `X' is a keyword symbol, or `#f' otherwise.


File: chicken.info,  Node: Unit library - Keywords - keyword->string,  Next: Unit library - Keywords - string->keyword,  Prev: Unit library - Keywords - keyword?,  Up: Unit library - Keywords

14.6.3 keyword->string
----------------------


[procedure] (keyword->string KEYWORD)
 Transforms `KEYWORD' into a string.


File: chicken.info,  Node: Unit library - Keywords - string->keyword,  Prev: Unit library - Keywords - keyword->string,  Up: Unit library - Keywords

14.6.4 string->keyword
----------------------


[procedure] (string->keyword STRING)
 Returns a keyword with the name `STRING'.


File: chicken.info,  Node: Unit library - Exceptions,  Next: Unit library - Environment information and system interface,  Prev: Unit library - Keywords,  Up: Unit library

14.7 Exceptions
===============

* Menu:

* Unit library - Exceptions - condition-case::
* Unit library - Exceptions - breakpoint::

   CHICKEN implements the (currently withdrawn) SRFI-12
(http://srfi.schemers.org/srfi-12/srfi-12.html) exception system. For
more information, see the SRFI-12
(http://srfi.schemers.org/srfi-12/srfi-12.html) document.


File: chicken.info,  Node: Unit library - Exceptions - condition-case,  Next: Unit library - Exceptions - breakpoint,  Up: Unit library - Exceptions

14.7.1 condition-case
---------------------


[syntax] (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 signaled 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-signaled 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
     _


File: chicken.info,  Node: Unit library - Exceptions - breakpoint,  Prev: Unit library - Exceptions - condition-case,  Up: Unit library - Exceptions

14.7.2 breakpoint
-----------------


[procedure] (breakpoint [NAME])
 Programmatically triggers a breakpoint (similar to the `,br' top-level
csi command).

All error-conditions signaled by the system are of kind `exn'. The
following composite conditions are additionally defined:

   <table>

   <tr><td> (exn arity)

   Signaled when a procedure is called with the wrong number of
arguments.

   </td></tr><tr><td> (exn type)

   Signaled on type-mismatch errors, for example when an argument of
the wrong type is passed to a built-in procedure.

   </td></tr><tr><td> (exn arithmetic)

   Signaled on arithmetic errors, like division by zero.

   </td></tr><tr><td> (exn i/o)

   Signaled on input/output errors.

   </td></tr><tr><td> (exn i/o file)

   Signaled on file-related errors.

   </td></tr><tr><td> (exn i/o net)

   Signaled on network errors.

   </td></tr><tr><td> (exn bounds)

   Signaled on errors caused by accessing non-existent elements of a
collection.

   </td></tr><tr><td> (exn runtime)

   Signaled on low-level runtime-system error-situations.

   </td></tr><tr><td> (exn runtime limit)

   Signaled when an internal limit is exceeded (like running out of
memory).

   </td></tr><tr><td> (exn match)

   Signaled on errors raised by failed matches (see the section on
`match').

   </td></tr><tr><td> (exn syntax)

   Signaled on syntax errors.

   </td></tr><tr><td> (exn breakpoint)

   Signaled when a breakpoint is reached.

   </td></tr>

   </table>

   Notes:

   * All error-exceptions (of the kind `exn') are non-continuable.

   * Error-exceptions of the `exn' kind have additional `arguments' and
     `location' properties that contain the arguments passed to the
     exception-handler and the name of the procedure where the error
     occurred (if available).

   * When the `posix' unit is available and used, then a user-interrupt
     (`signal/int') signals an exception of the kind `user-interrupt'.

   * the procedure `condition-property-accessor' accepts an optional
     third argument. If the condition does not have a value for the
     desired property and if the optional argument is given, no error
     is signaled and the accessor returns the third argument.

   * In composite conditions all properties are currently collected in
     a single property-list, so in the case that to conditions have the
     same named property, only one will be visible.



File: chicken.info,  Node: Unit library - Environment information and system interface,  Next: Unit library - Execution time,  Prev: Unit library - Exceptions,  Up: Unit library

14.8 Environment information and system interface
=================================================

* Menu:

* Unit library - Environment information and system interface - argv::
* Unit library - Environment information and system interface - exit::
* Unit library - Environment information and system interface - build-platform::
* Unit library - Environment information and system interface - chicken-version::
* Unit library - Environment information and system interface - errno::
* Unit library - Environment information and system interface - getenv::
* Unit library - Environment information and system interface - machine-byte-order::
* Unit library - Environment information and system interface - machine-type::
* Unit library - Environment information and system interface - on-exit::
* Unit library - Environment information and system interface - software-type::
* Unit library - Environment information and system interface - software-version::
* Unit library - Environment information and system interface - c-runtime::
* Unit library - Environment information and system interface - system::


File: chicken.info,  Node: Unit library - Environment information and system interface - argv,  Next: Unit library - Environment information and system interface - exit,  Up: Unit library - Environment information and system interface

14.8.1 argv
-----------


[procedure] (argv)
 Return a list of all supplied command-line arguments. The first item
in the list is a string containing the name of the executing program.
The other items are the arguments passed to the application. This list
is freshly created on every invocation of `(argv)'. It depends on the
host-shell whether arguments are expanded ('globbed') or not.


File: chicken.info,  Node: Unit library - Environment information and system interface - exit,  Next: Unit library - Environment information and system interface - build-platform,  Prev: Unit library - Environment information and system interface - argv,  Up: Unit library - Environment information and system interface

14.8.2 exit
-----------


[procedure] (exit [CODE])
 Exit the running process and return exit-code, which defaults to 0
(Invokes `exit-handler').

Note that pending `dynamic-wind' thunks are _not_ invoked when exiting
your program in this way.


File: chicken.info,  Node: Unit library - Environment information and system interface - build-platform,  Next: Unit library - Environment information and system interface - chicken-version,  Prev: Unit library - Environment information and system interface - exit,  Up: Unit library - Environment information and system interface

14.8.3 build-platform
---------------------


[procedure] (build-platform)
 Returns a symbol specifying the toolset which has been used for
building the executing system, which is one of the following:


cygwin
mingw32
gnu
intel
unknown


File: chicken.info,  Node: Unit library - Environment information and system interface - chicken-version,  Next: Unit library - Environment information and system interface - errno,  Prev: Unit library - Environment information and system interface - build-platform,  Up: Unit library - Environment information and system interface

14.8.4 chicken-version
----------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Environment information and system interface - errno,  Next: Unit library - Environment information and system interface - getenv,  Prev: Unit library - Environment information and system interface - chicken-version,  Up: Unit library - Environment information and system interface

14.8.5 errno
------------


[procedure] (errno)
 Returns the error code of the last system call.


File: chicken.info,  Node: Unit library - Environment information and system interface - getenv,  Next: Unit library - Environment information and system interface - machine-byte-order,  Prev: Unit library - Environment information and system interface - errno,  Up: Unit library - Environment information and system interface

14.8.6 getenv
-------------


[procedure] (getenv STRING)
 Returns the value of the environment variable `STRING' or `#f' if that
variable is not defined.


File: chicken.info,  Node: Unit library - Environment information and system interface - machine-byte-order,  Next: Unit library - Environment information and system interface - machine-type,  Prev: Unit library - Environment information and system interface - getenv,  Up: Unit library - Environment information and system interface

14.8.7 machine-byte-order
-------------------------


[procedure] (machine-byte-order)
 Returns the symbol `little-endian' or `big-endian', depending on the
machine's byte-order.


File: chicken.info,  Node: Unit library - Environment information and system interface - machine-type,  Next: Unit library - Environment information and system interface - on-exit,  Prev: Unit library - Environment information and system interface - machine-byte-order,  Up: Unit library - Environment information and system interface

14.8.8 machine-type
-------------------


[procedure] (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
ppc64
ia64
x86
x86-64
unknown


File: chicken.info,  Node: Unit library - Environment information and system interface - on-exit,  Next: Unit library - Environment information and system interface - software-type,  Prev: Unit library - Environment information and system interface - machine-type,  Up: Unit library - Environment information and system interface

14.8.9 on-exit
--------------


[procedure] (on-exit THUNK)
 Schedules the zero-argument procedures `THUNK' to be executed before
the process exits, either explicitly via `exit' or implicitly after
execution of the last top-level form. Note that finalizers for
unreferenced finalized data are run before exit procedures.


File: chicken.info,  Node: Unit library - Environment information and system interface - software-type,  Next: Unit library - Environment information and system interface - software-version,  Prev: Unit library - Environment information and system interface - on-exit,  Up: Unit library - Environment information and system interface

14.8.10 software-type
---------------------


[procedure] (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


File: chicken.info,  Node: Unit library - Environment information and system interface - software-version,  Next: Unit library - Environment information and system interface - c-runtime,  Prev: Unit library - Environment information and system interface - software-type,  Up: Unit library - Environment information and system interface

14.8.11 software-version
------------------------


[procedure] (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


File: chicken.info,  Node: Unit library - Environment information and system interface - c-runtime,  Next: Unit library - Environment information and system interface - system,  Prev: Unit library - Environment information and system interface - software-version,  Up: Unit library - Environment information and system interface

14.8.12 c-runtime
-----------------


[procedure] (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'.


File: chicken.info,  Node: Unit library - Environment information and system interface - system,  Prev: Unit library - Environment information and system interface - c-runtime,  Up: Unit library - Environment information and system interface

14.8.13 system
--------------


[procedure] (system STRING)
 Execute shell command. The functionality offered by this procedure
depends on the capabilities of the host shell. If the forking of a
subprocess failed, an exception is raised. Otherwise the return status
of the subprocess is returned unaltered.


File: chicken.info,  Node: Unit library - Execution time,  Next: Unit library - Interrupts and error-handling,  Prev: Unit library - Environment information and system interface,  Up: Unit library

14.9 Execution time
===================

* Menu:

* Unit library - Execution time - cpu-time::
* Unit library - Execution time - current-milliseconds::
* Unit library - Execution time - current-seconds::
* Unit library - Execution time - current-gc-milliseconds::


File: chicken.info,  Node: Unit library - Execution time - cpu-time,  Next: Unit library - Execution time - current-milliseconds,  Up: Unit library - Execution time

14.9.1 cpu-time
---------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Execution time - current-milliseconds,  Next: Unit library - Execution time - current-seconds,  Prev: Unit library - Execution time - cpu-time,  Up: Unit library - Execution time

14.9.2 current-milliseconds
---------------------------


[procedure] (current-milliseconds)
 Returns the number of milliseconds since process- or machine startup.


File: chicken.info,  Node: Unit library - Execution time - current-seconds,  Next: Unit library - Execution time - current-gc-milliseconds,  Prev: Unit library - Execution time - current-milliseconds,  Up: Unit library - Execution time

14.9.3 current-seconds
----------------------


[procedure] (current-seconds)
 Returns the number of seconds since midnight, Jan. 1, 1970.


File: chicken.info,  Node: Unit library - Execution time - current-gc-milliseconds,  Prev: Unit library - Execution time - current-seconds,  Up: Unit library - Execution time

14.9.4 current-gc-milliseconds
------------------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Interrupts and error-handling,  Next: Unit library - Garbage collection,  Prev: Unit library - Execution time,  Up: Unit library

14.10 Interrupts and error-handling
===================================

* Menu:

* Unit library - Interrupts and error-handling - enable-warnings::
* Unit library - Interrupts and error-handling - error::
* Unit library - Interrupts and error-handling - get-call-chain::
* Unit library - Interrupts and error-handling - print-call-chain::
* Unit library - Interrupts and error-handling - print-error-message::
* Unit library - Interrupts and error-handling - procedure-information::
* Unit library - Interrupts and error-handling - reset::
* Unit library - Interrupts and error-handling - warning::
* Unit library - Interrupts and error-handling - singlestep::


File: chicken.info,  Node: Unit library - Interrupts and error-handling - enable-warnings,  Next: Unit library - Interrupts and error-handling - error,  Up: Unit library - Interrupts and error-handling

14.10.1 enable-warnings
-----------------------


[procedure] (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 (whether warnings are enabled or
disabled) is global and not thread-local.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - error,  Next: Unit library - Interrupts and error-handling - get-call-chain,  Prev: Unit library - Interrupts and error-handling - enable-warnings,  Up: Unit library - Interrupts and error-handling

14.10.2 error
-------------


[procedure] (error [LOCATION] [STRING] EXP ...)
 Prints error message, writes all extra arguments to the value of
`(current-error-port)' and invokes the current exception-handler. This
conforms to SRFI-23 (http://srfi.schemers.org/srfi-23/srfi-23.html). If
`LOCATION' is given and a symbol, it specifies the _location_ (the name
of the procedure) where the error occurred.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - get-call-chain,  Next: Unit library - Interrupts and error-handling - print-call-chain,  Prev: Unit library - Interrupts and error-handling - error,  Up: Unit library - Interrupts and error-handling

14.10.3 get-call-chain
----------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - print-call-chain,  Next: Unit library - Interrupts and error-handling - print-error-message,  Prev: Unit library - Interrupts and error-handling - get-call-chain,  Up: Unit library - Interrupts and error-handling

14.10.4 print-call-chain
------------------------


[procedure] (print-call-chain [PORT [START [THREAD]]])
 Prints a backtrace of the procedure call history to `PORT', which
defaults to `(current-output-port)'.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - print-error-message,  Next: Unit library - Interrupts and error-handling - procedure-information,  Prev: Unit library - Interrupts and error-handling - print-call-chain,  Up: Unit library - Interrupts and error-handling

14.10.5 print-error-message
---------------------------


[procedure] (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:"'.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - procedure-information,  Next: Unit library - Interrupts and error-handling - reset,  Prev: Unit library - Interrupts and error-handling - print-error-message,  Up: Unit library - Interrupts and error-handling

14.10.6 procedure-information
-----------------------------


[procedure] (procedure-information PROC)
 Returns an s-expression with debug information for the procedure
`PROC', or `#f', if `PROC' has no associated debug information.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - reset,  Next: Unit library - Interrupts and error-handling - warning,  Prev: Unit library - Interrupts and error-handling - procedure-information,  Up: Unit library - Interrupts and error-handling

14.10.7 reset
-------------


[procedure] (reset)
 Reset program (Invokes `reset-handler').


File: chicken.info,  Node: Unit library - Interrupts and error-handling - warning,  Next: Unit library - Interrupts and error-handling - singlestep,  Prev: Unit library - Interrupts and error-handling - reset,  Up: Unit library - Interrupts and error-handling

14.10.8 warning
---------------


[procedure] (warning STRING EXP ...)
 Displays a warning message (if warnings are enabled with
`enable-warnings') and continues execution.


File: chicken.info,  Node: Unit library - Interrupts and error-handling - singlestep,  Prev: Unit library - Interrupts and error-handling - warning,  Up: Unit library - Interrupts and error-handling

14.10.9 singlestep
------------------


[procedure] (singlestep THUNK)
 Executes the code in the zero-procedure `THUNK' in single-stepping
mode.


File: chicken.info,  Node: Unit library - Garbage collection,  Next: Unit library - Other control structures,  Prev: Unit library - Interrupts and error-handling,  Up: Unit library

14.11 Garbage collection
========================

* Menu:

* Unit library - Garbage collection - gc::
* Unit library - Garbage collection - memory-statistics::
* Unit library - Garbage collection - set-finalizer!::
* Unit library - Garbage collection - set-gc-report!::


File: chicken.info,  Node: Unit library - Garbage collection - gc,  Next: Unit library - Garbage collection - memory-statistics,  Up: Unit library - Garbage collection

14.11.1 gc
----------


[procedure] (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. An
explicit `#t' argument will cause all pending finalizers to be executed.


File: chicken.info,  Node: Unit library - Garbage collection - memory-statistics,  Next: Unit library - Garbage collection - set-finalizer!,  Prev: Unit library - Garbage collection - gc,  Up: Unit library - Garbage collection

14.11.2 memory-statistics
-------------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Garbage collection - set-finalizer!,  Next: Unit library - Garbage collection - set-gc-report!,  Prev: Unit library - Garbage collection - memory-statistics,  Up: Unit library - Garbage collection

14.11.3 set-finalizer!
----------------------


[procedure] (set-finalizer! X PROC)
 Registers a procedure of one argument `PROC', that will be called as
soon as the non-immediate data object `X' is about to be
garbage-collected (with that object as its argument). Note that the
finalizer will not be called while interrupts are disabled. This
procedure returns `X'.

Finalizers are invoked asynchronously, in the thread that happens to be
currently running.


File: chicken.info,  Node: Unit library - Garbage collection - set-gc-report!,  Prev: Unit library - Garbage collection - set-finalizer!,  Up: Unit library - Garbage collection

14.11.4 set-gc-report!
----------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Other control structures,  Next: Unit library - String utilities,  Prev: Unit library - Garbage collection,  Up: Unit library

14.12 Other control structures
==============================

* Menu:

* Unit library - Other control structures - promise?::


File: chicken.info,  Node: Unit library - Other control structures - promise?,  Up: Unit library - Other control structures

14.12.1 promise?
----------------


[procedure] (promise? X)
 Returns `#t' if `X' is a promise returned by `delay', or `#f'
otherwise.


File: chicken.info,  Node: Unit library - String utilities,  Next: Unit library - Generating uninterned symbols,  Prev: Unit library - Other control structures,  Up: Unit library

14.13 String utilities
======================

* Menu:

* Unit library - String utilities - reverse-list->string::


File: chicken.info,  Node: Unit library - String utilities - reverse-list->string,  Up: Unit library - String utilities

14.13.1 reverse-list->string
----------------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Generating uninterned symbols,  Next: Unit library - Standard Input/Output,  Prev: Unit library - String utilities,  Up: Unit library

14.14 Generating uninterned symbols
===================================

* Menu:

* Unit library - Generating uninterned symbols - gensym::
* Unit library - Generating uninterned symbols - string->uninterned-symbol::


File: chicken.info,  Node: Unit library - Generating uninterned symbols - gensym,  Next: Unit library - Generating uninterned symbols - string->uninterned-symbol,  Up: Unit library - Generating uninterned symbols

14.14.1 gensym
--------------


[procedure] (gensym [STRING-OR-SYMBOL])
 Returns a newly created uninterned symbol. If an argument is provided,
the new symbol is prefixed with that argument.


File: chicken.info,  Node: Unit library - Generating uninterned symbols - string->uninterned-symbol,  Prev: Unit library - Generating uninterned symbols - gensym,  Up: Unit library - Generating uninterned symbols

14.14.2 string->uninterned-symbol
---------------------------------


[procedure] (string->uninterned-symbol STRING)
 Returns a newly created, unique symbol with the name `STRING'.


File: chicken.info,  Node: Unit library - Standard Input/Output,  Next: Unit library - User-defined named characters,  Prev: Unit library - Generating uninterned symbols,  Up: Unit library

14.15 Standard Input/Output
===========================

* Menu:

* Unit library - Standard Input/Output - port?::
* Unit library - Standard Input/Output - print::
* Unit library - Standard Input/Output - print*::


File: chicken.info,  Node: Unit library - Standard Input/Output - port?,  Next: Unit library - Standard Input/Output - print,  Up: Unit library - Standard Input/Output

14.15.1 port?
-------------


[procedure] (port? X)
 Returns `#t' if `X' is a port object or `#f' otherwise.


File: chicken.info,  Node: Unit library - Standard Input/Output - print,  Next: Unit library - Standard Input/Output - print*,  Prev: Unit library - Standard Input/Output - port?,  Up: Unit library - Standard Input/Output

14.15.2 print
-------------


[procedure] (print [EXP1 ...])
 Outputs the optional arguments `EXP1 ...' using `display' and writes a
newline character to the port that is the value of
`(current-output-port)'. Returns `(void)'.


File: chicken.info,  Node: Unit library - Standard Input/Output - print*,  Prev: Unit library - Standard Input/Output - print,  Up: Unit library - Standard Input/Output

14.15.3 print*
--------------


[procedure] (print* [EXP1 ...])
 Similar to `print', but does not output a terminating newline
character and performs a `flush-output' after writing its arguments.


File: chicken.info,  Node: Unit library - User-defined named characters,  Next: Unit library - Blobs,  Prev: Unit library - Standard Input/Output,  Up: Unit library

14.16 User-defined named characters
===================================

* Menu:

* Unit library - User-defined named characters - char-name::


File: chicken.info,  Node: Unit library - User-defined named characters - char-name,  Up: Unit library - User-defined named characters

14.16.1 char-name
-----------------


[procedure] (char-name SYMBOL-OR-CHAR [CHAR])
 This procedure can be used to inquire about character names or to
define new ones. With a single argument the 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


File: chicken.info,  Node: Unit library - Blobs,  Next: Unit library - Vectors,  Prev: Unit library - User-defined named characters,  Up: Unit library

14.17 Blobs
===========

* Menu:

* Unit library - Blobs - make-blob::
* Unit library - Blobs - blob?::
* Unit library - Blobs - blob-size::
* Unit library - Blobs - blob->string::
* Unit library - Blobs - string->blob::
* Unit library - Blobs - blob=?::

   "blobs" are collections of unstructured bytes. You can't do much
with them, but allow conversion to and from SRFI-4 number vectors.


File: chicken.info,  Node: Unit library - Blobs - make-blob,  Next: Unit library - Blobs - blob?,  Up: Unit library - Blobs

14.17.1 make-blob
-----------------


[procedure] (make-blob SIZE)
 Returns a blob object of `SIZE' bytes, aligned on an 8-byte boundary,
uninitialized.


File: chicken.info,  Node: Unit library - Blobs - blob?,  Next: Unit library - Blobs - blob-size,  Prev: Unit library - Blobs - make-blob,  Up: Unit library - Blobs

14.17.2 blob?
-------------


[procedure] (blob? X)
 Returns `#t' if `X' is a blob object, or `#f' otherwise.


File: chicken.info,  Node: Unit library - Blobs - blob-size,  Next: Unit library - Blobs - blob->string,  Prev: Unit library - Blobs - blob?,  Up: Unit library - Blobs

14.17.3 blob-size
-----------------


[procedure] (blob-size BLOB)
 Returns the number of bytes in `BLOB'.


File: chicken.info,  Node: Unit library - Blobs - blob->string,  Next: Unit library - Blobs - string->blob,  Prev: Unit library - Blobs - blob-size,  Up: Unit library - Blobs

14.17.4 blob->string
--------------------


[procedure] (blob->string BLOB)
 Returns a string with the contents of `BLOB'.


File: chicken.info,  Node: Unit library - Blobs - string->blob,  Next: Unit library - Blobs - blob=?,  Prev: Unit library - Blobs - blob->string,  Up: Unit library - Blobs

14.17.5 string->blob
--------------------


[procedure] (string->blob STRING)
 Returns a blob with the contents of `STRING'.


File: chicken.info,  Node: Unit library - Blobs - blob=?,  Prev: Unit library - Blobs - string->blob,  Up: Unit library - Blobs

14.17.6 blob=?
--------------


[procedure] (blob=? BLOB1 BLOB2)
 Returns `#t' if the two argument blobs are of the same size and have
the same content.


File: chicken.info,  Node: Unit library - Vectors,  Next: Unit library - The unspecified value,  Prev: Unit library - Blobs,  Up: Unit library

14.18 Vectors
=============

* Menu:

* Unit library - Vectors - vector-copy!::
* Unit library - Vectors - vector-resize::


File: chicken.info,  Node: Unit library - Vectors - vector-copy!,  Next: Unit library - Vectors - vector-resize,  Up: Unit library - Vectors

14.18.1 vector-copy!
--------------------


[procedure] (vector-copy! VECTOR1 VECTOR2 [COUNT])
 Copies contents of `VECTOR1' into `VECTOR2'. If the argument `COUNT'
is given, it specifies the maximal number of elements to be copied. If
not given, the minimum of the lengths of the argument vectors is copied.

Exceptions: `(exn bounds)'


File: chicken.info,  Node: Unit library - Vectors - vector-resize,  Prev: Unit library - Vectors - vector-copy!,  Up: Unit library - Vectors

14.18.2 vector-resize
---------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - The unspecified value,  Next: Unit library - Continuations,  Prev: Unit library - Vectors,  Up: Unit library

14.19 The unspecified value
===========================

* Menu:

* Unit library - The unspecified value - void::


File: chicken.info,  Node: Unit library - The unspecified value - void,  Up: Unit library - The unspecified value

14.19.1 void
------------


[procedure] (void)
 Returns an unspecified value.


File: chicken.info,  Node: Unit library - Continuations,  Next: Unit library - Setters,  Prev: Unit library - The unspecified value,  Up: Unit library

14.20 Continuations
===================

* Menu:

* Unit library - Continuations - call/cc::
* Unit library - Continuations - continuation-capture::
* Unit library - Continuations - continuation?::
* Unit library - Continuations - continuation-graft::
* Unit library - Continuations - continuation-return::


File: chicken.info,  Node: Unit library - Continuations - call/cc,  Next: Unit library - Continuations - continuation-capture,  Up: Unit library - Continuations

14.20.1 call/cc
---------------


[procedure] (call/cc PROCEDURE)
 An alias for `call-with-current-continuation'.


File: chicken.info,  Node: Unit library - Continuations - continuation-capture,  Next: Unit library - Continuations - continuation?,  Prev: Unit library - Continuations - call/cc,  Up: Unit library - Continuations

14.20.2 continuation-capture
----------------------------


[procedure] (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
(http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf) _A
Better API for first class Continuations_ by Marc Feeley.


File: chicken.info,  Node: Unit library - Continuations - continuation?,  Next: Unit library - Continuations - continuation-graft,  Prev: Unit library - Continuations - continuation-capture,  Up: Unit library - Continuations

14.20.3 continuation?
---------------------


[procedure] (continuation? X)
 Returns `#t' if `X' is a continuation object, or `#f' otherwise.
Please note that this applies only to continuations created by the
Continuation API, but not by call/cc, i.e.:
`(call-with-current-continuation continuation?)' returns `#f', whereas
`(continuation-capture continuation?)' returns `#t'.


File: chicken.info,  Node: Unit library - Continuations - continuation-graft,  Next: Unit library - Continuations - continuation-return,  Prev: Unit library - Continuations - continuation?,  Up: Unit library - Continuations

14.20.4 continuation-graft
--------------------------


[procedure] (continuation-graft CONT THUNK)
 Calls the procedure `THUNK' with no arguments and the implicit
continuation `CONT'.


File: chicken.info,  Node: Unit library - Continuations - continuation-return,  Prev: Unit library - Continuations - continuation-graft,  Up: Unit library - Continuations

14.20.5 continuation-return
---------------------------


[procedure] (continuation-return CONT VALUE ...)
 Returns the value(s) to the continuation `CONT'. `continuation-return'
could be implemented like this:

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


File: chicken.info,  Node: Unit library - Setters,  Next: Unit library - Reader extensions,  Prev: Unit library - Continuations,  Up: Unit library

14.21 Setters
=============

* Menu:

* Unit library - Setters - setter::
* Unit library - Setters - getter-with-setter::

   SRFI-17 is fully implemented. For more information see: SRFI-17
(http://srfi.schemers.org/srfi-17/srfi-17.html).


File: chicken.info,  Node: Unit library - Setters - setter,  Next: Unit library - Setters - getter-with-setter,  Up: Unit library - Setters

14.21.1 setter
--------------


[procedure] (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).


File: chicken.info,  Node: Unit library - Setters - getter-with-setter,  Prev: Unit library - Setters - setter,  Up: Unit library - Setters

14.21.2 getter-with-setter
--------------------------


[procedure] (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.


File: chicken.info,  Node: Unit library - Reader extensions,  Next: Unit library - Property lists,  Prev: Unit library - Setters,  Up: Unit library

14.22 Reader extensions
=======================

* Menu:

* Unit library - Reader extensions - define-reader-ctor::
* Unit library - Reader extensions - set-read-syntax!::
* Unit library - Reader extensions - set-sharp-read-syntax!::
* Unit library - Reader extensions - set-parameterized-read-syntax!::
* Unit library - Reader extensions - copy-read-table::


File: chicken.info,  Node: Unit library - Reader extensions - define-reader-ctor,  Next: Unit library - Reader extensions - set-read-syntax!,  Up: Unit library - Reader extensions

14.22.1 define-reader-ctor
--------------------------


[procedure] (define-reader-ctor SYMBOL PROC)
 Define new read-time constructor for `#,' read syntax. For further
information, see the documentation for SRFI-10
(http://srfi.schemers.org/srfi-10/srfi-10.html).


File: chicken.info,  Node: Unit library - Reader extensions - set-read-syntax!,  Next: Unit library - Reader extensions - set-sharp-read-syntax!,  Prev: Unit library - Reader extensions - define-reader-ctor,  Up: Unit library - Reader extensions

14.22.2 set-read-syntax!
------------------------


[procedure] (set-read-syntax! CHAR-OR-SYMBOL PROC)
 When the reader encounters 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)
     _
If `CHAR-OR-SYMBOL' is a symbol, then a so-called _read-mark_ handler
is defined. In that case the handler procedure will be called when a
character-sequence of the form


#!SYMBOL
 is encountered.

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


File: chicken.info,  Node: Unit library - Reader extensions - set-sharp-read-syntax!,  Next: Unit library - Reader extensions - set-parameterized-read-syntax!,  Prev: Unit library - Reader extensions - set-read-syntax!,  Up: Unit library - Reader extensions

14.22.3 set-sharp-read-syntax!
------------------------------


[procedure] (set-sharp-read-syntax! CHAR-OR-SYMBOL PROC)
 Similar to `set-read-syntax!', but allows defining new `#<CHAR> ...'
reader syntax. If the first argument is a symbol, then this procedure
is equivalent to `set-read-syntax!'.


File: chicken.info,  Node: Unit library - Reader extensions - set-parameterized-read-syntax!,  Next: Unit library - Reader extensions - copy-read-table,  Prev: Unit library - Reader extensions - set-sharp-read-syntax!,  Up: Unit library - Reader extensions

14.22.4 set-parameterized-read-syntax!
--------------------------------------


[procedure] (set-parameterized-read-syntax! CHAR-OR-SYMBOL PROC)
 Similar to `set-sharp-read-syntax!', but intended for defining reader
syntax of the form `#<NUMBER><CHAR> ...'. The handler procedure `PROC'
will be called with two arguments: the input port and the number
preceding the dispatching character. If the first argument is a symbol,
then this procedure is equivalent to `set-read-syntax!'.


File: chicken.info,  Node: Unit library - Reader extensions - copy-read-table,  Prev: Unit library - Reader extensions - set-parameterized-read-syntax!,  Up: Unit library - Reader extensions

14.22.5 copy-read-table
-----------------------


[procedure] (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)'.


File: chicken.info,  Node: Unit library - Property lists,  Prev: Unit library - Reader extensions,  Up: Unit library

14.23 Property lists
====================

* Menu:

* Unit library - Property lists - get::
* Unit library - Property lists - put!::
* Unit library - Property lists - remprop!::
* Unit library - Property lists - symbol-plist::
* Unit library - Property lists - get-properties::

   As in other Lisp dialects, CHICKEN supports "property lists"
associated with symbols. Properties are accessible via a key that can
be any kind of value but which will be compared using `eq?'.


File: chicken.info,  Node: Unit library - Property lists - get,  Next: Unit library - Property lists - put!,  Up: Unit library - Property lists

14.23.1 get
-----------


 [procedure] (get SYMBOL PROPERTY [DEFAULT])
 Returns the value stored under the key `PROPERTY' in the property list
of `SYMBOL'. If no such property is stored, returns `DEFAULT'. The
`DEFAULT' is optional and defaults to `#f'.


File: chicken.info,  Node: Unit library - Property lists - put!,  Next: Unit library - Property lists - remprop!,  Prev: Unit library - Property lists - get,  Up: Unit library - Property lists

14.23.2 put!
------------


 [procedure] (put! SYMBOL PROPERTY VALUE)
 [setter] (set! (get SYMBOL PROPERTY) VALUE)
 Stores `VALUE' under the key `PROPERTY' in the property list of
`SYMBOL' replacing any previously stored value.


File: chicken.info,  Node: Unit library - Property lists - remprop!,  Next: Unit library - Property lists - symbol-plist,  Prev: Unit library - Property lists - put!,  Up: Unit library - Property lists

14.23.3 remprop!
----------------


 [procedure] (remprop! SYMBOL PROPERTY)
 Deletes the first property matching the key `PROPERTY' in the property
list of `SYMBOL'. Returns `#t' when a deletion performed, and `#f'
otherwise.


File: chicken.info,  Node: Unit library - Property lists - symbol-plist,  Next: Unit library - Property lists - get-properties,  Prev: Unit library - Property lists - remprop!,  Up: Unit library - Property lists

14.23.4 symbol-plist
--------------------


 [procedure] (symbol-plist SYMBOL)
 [setter] (set! (symbol-plist SYMBOL) LST)
 Returns the property list of `SYMBOL' or sets it.


File: chicken.info,  Node: Unit library - Property lists - get-properties,  Prev: Unit library - Property lists - symbol-plist,  Up: Unit library - Property lists

14.23.5 get-properties
----------------------


 [procedure] (get-properties SYMBOL PROPERTIES)
 Searches the property list of `SYMBOL' for the first property with a
key in the list `PROPERTIES'. Returns 3 values: the matching property
key, value, and the tail of property list after the matching property.
When no match found all values are `#f'.

`PROPERTIES' may also be an atom, in which case it is treated as a list
of one element.

   Previous: *Note Parameters: Parameters.

   Next: *Note Unit eval: Unit eval.


File: chicken.info,  Node: Unit eval,  Next: Unit data-structures,  Prev: Unit library,  Up: Top

15 Unit eval
************

* Menu:

* Unit eval - Loading code::
* Unit eval - Read-eval-print loop::
* Unit eval - Macros::
* Unit eval - Loading extension libraries::
* Unit eval - System information::
* Unit eval - Eval::

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


File: chicken.info,  Node: Unit eval - Loading code,  Next: Unit eval - Read-eval-print loop,  Up: Unit eval

15.1 Loading code
=================

* Menu:

* Unit eval - Loading code - load::
* Unit eval - Loading code - load-relative::
* Unit eval - Loading code - load-noisily::
* Unit eval - Loading code - load-library::
* Unit eval - Loading code - set-dynamic-load-mode!::


File: chicken.info,  Node: Unit eval - Loading code - load,  Next: Unit eval - Loading code - load-relative,  Up: Unit eval - Loading code

15.1.1 load
-----------


[procedure] (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 reloading compiled code dynamically is still
experimental.


File: chicken.info,  Node: Unit eval - Loading code - load-relative,  Next: Unit eval - Loading code - load-noisily,  Prev: Unit eval - Loading code - load,  Up: Unit eval - Loading code

15.1.2 load-relative
--------------------


[procedure] (load-relative FILE [EVALPROC])
 Similar to `load', but loads `FILE' relative to the path of the
currently loaded file.


File: chicken.info,  Node: Unit eval - Loading code - load-noisily,  Next: Unit eval - Loading code - load-library,  Prev: Unit eval - Loading code - load-relative,  Up: Unit eval - Loading code

15.1.3 load-noisily
-------------------


[procedure] (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.

See also the load-verbose
(http://chicken.wiki.br/Parameters#load-verbose) parameter.


File: chicken.info,  Node: Unit eval - Loading code - load-library,  Next: Unit eval - Loading code - set-dynamic-load-mode!,  Prev: Unit eval - Loading code - load-noisily,  Up: Unit eval - Loading code

15.1.4 load-library
-------------------


[procedure] (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.


File: chicken.info,  Node: Unit eval - Loading code - set-dynamic-load-mode!,  Prev: Unit eval - Loading code - load-library,  Up: Unit eval - Loading code

15.1.5 set-dynamic-load-mode!
-----------------------------


[procedure] (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.


File: chicken.info,  Node: Unit eval - Read-eval-print loop,  Next: Unit eval - Macros,  Prev: Unit eval - Loading code,  Up: Unit eval

15.2 Read-eval-print loop
=========================

* Menu:

* Unit eval - Read-eval-print loop - repl::


File: chicken.info,  Node: Unit eval - Read-eval-print loop - repl,  Up: Unit eval - Read-eval-print loop

15.2.1 repl
-----------


[procedure] (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 exception-handler to display a message, write any arguments
to the value of `(current-error-port)' and reset.


File: chicken.info,  Node: Unit eval - Macros,  Next: Unit eval - Loading extension libraries,  Prev: Unit eval - Read-eval-print loop,  Up: Unit eval

15.3 Macros
===========

* Menu:

* Unit eval - Macros - get-line-number::
* Unit eval - Macros - macro?::
* Unit eval - Macros - macroexpand::
* Unit eval - Macros - macroexpand-1::
* Unit eval - Macros - undefine-macro!::
* Unit eval - Macros - syntax-error::


File: chicken.info,  Node: Unit eval - Macros - get-line-number,  Next: Unit eval - Macros - macro?,  Up: Unit eval - Macros

15.3.1 get-line-number
----------------------


[procedure] (get-line-number EXPR)
 If `EXPR' is a pair with the car being a symbol, and line-number
information is available for this expression, then this procedure
returns the associated line number. If line-number information is not
available, then `#f' is returned.  Note that line-number information
for expressions is only available in the compiler.


File: chicken.info,  Node: Unit eval - Macros - macro?,  Next: Unit eval - Macros - macroexpand,  Prev: Unit eval - Macros - get-line-number,  Up: Unit eval - Macros

15.3.2 macro?
-------------


[procedure] (macro? SYMBOL)
 Returns `#t' if there exists a macro-definition for `SYMBOL'.


File: chicken.info,  Node: Unit eval - Macros - macroexpand,  Next: Unit eval - Macros - macroexpand-1,  Prev: Unit eval - Macros - macro?,  Up: Unit eval - Macros

15.3.3 macroexpand
------------------


[procedure] (macroexpand X)
 If `X' is a macro-form, expand the macro (and repeat expansion until
expression is a non-macro form).  Returns the resulting expression.


File: chicken.info,  Node: Unit eval - Macros - macroexpand-1,  Next: Unit eval - Macros - undefine-macro!,  Prev: Unit eval - Macros - macroexpand,  Up: Unit eval - Macros

15.3.4 macroexpand-1
--------------------


[procedure] (macroexpand-1 X)
 If `X' is a macro-form, expand the macro.  Returns the resulting
expression.


File: chicken.info,  Node: Unit eval - Macros - undefine-macro!,  Next: Unit eval - Macros - syntax-error,  Prev: Unit eval - Macros - macroexpand-1,  Up: Unit eval - Macros

15.3.5 undefine-macro!
----------------------


[procedure] (undefine-macro! SYMBOL)
 Remove the current macro-definition of the macro named `SYMBOL'.


File: chicken.info,  Node: Unit eval - Macros - syntax-error,  Prev: Unit eval - Macros - undefine-macro!,  Up: Unit eval - Macros

15.3.6 syntax-error
-------------------


[procedure] (syntax-error [LOCATION] MESSAGE ARGUMENT ...)
 Signals an exception of the kind `(exn syntax)'. Otherwise identical
to  `error'.


File: chicken.info,  Node: Unit eval - Loading extension libraries,  Next: Unit eval - System information,  Prev: Unit eval - Macros,  Up: Unit eval

15.4 Loading extension libraries
================================

* Menu:

* Unit eval - Loading extension libraries - repository-path::
* Unit eval - Loading extension libraries - extension-information::
* Unit eval - Loading extension libraries - provide::
* Unit eval - Loading extension libraries - provided?::
* Unit eval - Loading extension libraries - require::
* Unit eval - Loading extension libraries - set-extension-specifier!::

   This functionality is only available on platforms that support
dynamic loading of compiled code. Currently Linux, BSD, Solaris,
Windows (with Cygwin) and HP/UX are supported.


File: chicken.info,  Node: Unit eval - Loading extension libraries - repository-path,  Next: Unit eval - Loading extension libraries - extension-information,  Up: Unit eval - Loading extension libraries

15.4.1 repository-path
----------------------

[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' or the default library path (usually
`/usr/local/lib/chicken' on UNIX systems).


File: chicken.info,  Node: Unit eval - Loading extension libraries - extension-information,  Next: Unit eval - Loading extension libraries - provide,  Prev: Unit eval - Loading extension libraries - repository-path,  Up: Unit eval - Loading extension libraries

15.4.2 extension-information
----------------------------


[procedure] (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'.


File: chicken.info,  Node: Unit eval - Loading extension libraries - provide,  Next: Unit eval - Loading extension libraries - provided?,  Prev: Unit eval - Loading extension libraries - extension-information,  Up: Unit eval - Loading extension libraries

15.4.3 provide
--------------


[procedure] (provide ID ...)
 Registers the extension IDs `ID ...' as loaded. This is mainly
intended to provide aliases for certain extension identifiers.


File: chicken.info,  Node: Unit eval - Loading extension libraries - provided?,  Next: Unit eval - Loading extension libraries - require,  Prev: Unit eval - Loading extension libraries - provide,  Up: Unit eval - Loading extension libraries

15.4.4 provided?
----------------


[procedure] (provided? ID ...)
 Returns `#t' if the extension with the IDs `ID ...' are currently
loaded, or `#f' otherwise.


File: chicken.info,  Node: Unit eval - Loading extension libraries - require,  Next: Unit eval - Loading extension libraries - set-extension-specifier!,  Prev: Unit eval - Loading extension libraries - provided?,  Up: Unit eval - Loading extension libraries

15.4.5 require
--------------


[procedure] (require ID ...)
[procedure] (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:

   * the current include path, which defaults to the pathnames given in
     `CHICKEN_INCLUDE_PATH'.

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


File: chicken.info,  Node: Unit eval - Loading extension libraries - set-extension-specifier!,  Prev: Unit eval - Loading extension libraries - require,  Up: Unit eval - Loading extension libraries

15.4.6 set-extension-specifier!
-------------------------------


[procedure] (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.


File: chicken.info,  Node: Unit eval - System information,  Next: Unit eval - Eval,  Prev: Unit eval - Loading extension libraries,  Up: Unit eval

15.5 System information
=======================

* Menu:

* Unit eval - System information - chicken-home::


File: chicken.info,  Node: Unit eval - System information - chicken-home,  Up: Unit eval - System information

15.5.1 chicken-home
-------------------


[procedure] (chicken-home)
 Returns a string given the installation directory (usually
`/usr/local/share/chicken' on UNIX-like systems). As a last option, if
the environment variable `CHICKEN_PREFIX' is set, then `chicken-home'
will return `$CHICKEN_PREFIX/share'.


File: chicken.info,  Node: Unit eval - Eval,  Prev: Unit eval - System information,  Up: Unit eval

15.6 Eval
=========

* Menu:

* Unit eval - Eval - eval::


File: chicken.info,  Node: Unit eval - Eval - eval,  Up: Unit eval - Eval

15.6.1 eval
-----------


[procedure] (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)'.

Previous: *Note Unit library: Unit library.

   Next: *Note Unit extras: Unit extras.


File: chicken.info,  Node: Unit data-structures,  Next: Unit ports,  Prev: Unit eval,  Up: Top

16 Unit data-structures
***********************

* Menu:

* Unit data-structures - Lists::
* Unit data-structures - Queues::
* Unit data-structures - Sorting::
* Unit data-structures - Random numbers::
* Unit data-structures - Strings::
* Unit data-structures - Combinators::
* Unit data-structures - Binary searching::

   This unit contains a collection of procedures related to data
structures.  This unit is used by default, unless the program is
compiled with the `-explicit-use' option.


File: chicken.info,  Node: Unit data-structures - Lists,  Next: Unit data-structures - Queues,  Up: Unit data-structures

16.1 Lists
==========

* Menu:

* Unit data-structures - Lists - alist-ref::
* Unit data-structures - Lists - alist-update!::
* Unit data-structures - Lists - atom?::
* Unit data-structures - Lists - rassoc::
* Unit data-structures - Lists - butlast::
* Unit data-structures - Lists - chop::
* Unit data-structures - Lists - compress::
* Unit data-structures - Lists - flatten::
* Unit data-structures - Lists - intersperse::
* Unit data-structures - Lists - join::
* Unit data-structures - Lists - shuffle::
* Unit data-structures - Lists - tail?::


File: chicken.info,  Node: Unit data-structures - Lists - alist-ref,  Next: Unit data-structures - Lists - alist-update!,  Up: Unit data-structures - Lists

16.1.1 alist-ref
----------------


[procedure] (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').


File: chicken.info,  Node: Unit data-structures - Lists - alist-update!,  Next: Unit data-structures - Lists - atom?,  Prev: Unit data-structures - Lists - alist-ref,  Up: Unit data-structures - Lists

16.1.2 alist-update!
--------------------


[procedure] (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?'.


File: chicken.info,  Node: Unit data-structures - Lists - atom?,  Next: Unit data-structures - Lists - rassoc,  Prev: Unit data-structures - Lists - alist-update!,  Up: Unit data-structures - Lists

16.1.3 atom?
------------


[procedure] (atom? X)
 Returns `#t' if `X' is not a pair. This is identical to `not-pair?'
from *Note Unit srfi-1: Unit srfi-1. but kept for historical reasons.


File: chicken.info,  Node: Unit data-structures - Lists - rassoc,  Next: Unit data-structures - Lists - butlast,  Prev: Unit data-structures - Lists - atom?,  Up: Unit data-structures - Lists

16.1.4 rassoc
-------------


[procedure] (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?'.


File: chicken.info,  Node: Unit data-structures - Lists - butlast,  Next: Unit data-structures - Lists - chop,  Prev: Unit data-structures - Lists - rassoc,  Up: Unit data-structures - Lists

16.1.5 butlast
--------------


[procedure] (butlast LIST)
 Returns a fresh list with all elements but the last of `LIST'.


File: chicken.info,  Node: Unit data-structures - Lists - chop,  Next: Unit data-structures - Lists - compress,  Prev: Unit data-structures - Lists - butlast,  Up: Unit data-structures - Lists

16.1.6 chop
-----------


[procedure] (chop LIST N)
 Returns a new list of sublists, where each sublist contains `N'
elements of `LIST'. If `LIST' has a length that is not a multiple of
`N', then the last sublist contains the remaining elements.

     (chop '(1 2 3 4 5 6) 2) =*=>* ((1 2) (3 4) (5 6))
     (chop '(a b c d) 3)     =*=>* ((a b c) (d))


File: chicken.info,  Node: Unit data-structures - Lists - compress,  Next: Unit data-structures - Lists - flatten,  Prev: Unit data-structures - Lists - chop,  Up: Unit data-structures - Lists

16.1.7 compress
---------------


[procedure] (compress BLIST LIST)
 Returns a new list with elements taken from `LIST' with corresponding
true values in the list `BLIST'.

     (*define* *nums* '(99 100 110 401 1234))
     (compress (map odd? nums) nums)      =*=>* (99 401)


File: chicken.info,  Node: Unit data-structures - Lists - flatten,  Next: Unit data-structures - Lists - intersperse,  Prev: Unit data-structures - Lists - compress,  Up: Unit data-structures - Lists

16.1.8 flatten
--------------


[procedure] (flatten LIST1 ...)
 Returns `LIST1 ...' concatenated together, with nested lists removed
(flattened).


File: chicken.info,  Node: Unit data-structures - Lists - intersperse,  Next: Unit data-structures - Lists - join,  Prev: Unit data-structures - Lists - flatten,  Up: Unit data-structures - Lists

16.1.9 intersperse
------------------


[procedure] (intersperse LIST X)
 Returns a new list with `X' placed between each element.


File: chicken.info,  Node: Unit data-structures - Lists - join,  Next: Unit data-structures - Lists - shuffle,  Prev: Unit data-structures - Lists - intersperse,  Up: Unit data-structures - Lists

16.1.10 join
------------


[procedure] (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)) )


File: chicken.info,  Node: Unit data-structures - Lists - shuffle,  Next: Unit data-structures - Lists - tail?,  Prev: Unit data-structures - Lists - join,  Up: Unit data-structures - Lists

16.1.11 shuffle
---------------


[procedure] (shuffle LIST RANDOM)
 Returns `LIST' with its elements sorted in a random order given by
procedure RANDOM.


File: chicken.info,  Node: Unit data-structures - Lists - tail?,  Prev: Unit data-structures - Lists - shuffle,  Up: Unit data-structures - Lists

16.1.12 tail?
-------------


[procedure] (tail? X LIST)
 Returns true if `X' is one of the tails (cdr's) of `LIST'.


File: chicken.info,  Node: Unit data-structures - Queues,  Next: Unit data-structures - Sorting,  Prev: Unit data-structures - Lists,  Up: Unit data-structures

16.2 Queues
===========

* Menu:

* Unit data-structures - Queues - list->queue::
* Unit data-structures - Queues - make-queue::
* Unit data-structures - Queues - queue?::
* Unit data-structures - Queues - queue->list::
* Unit data-structures - Queues - queue-add!::
* Unit data-structures - Queues - queue-empty?::
* Unit data-structures - Queues - queue-first::
* Unit data-structures - Queues - queue-last::
* Unit data-structures - Queues - queue-remove!::
* Unit data-structures - Queues - queue-push-back!::
* Unit data-structures - Queues - queue-push-back-list!::


File: chicken.info,  Node: Unit data-structures - Queues - list->queue,  Next: Unit data-structures - Queues - make-queue,  Up: Unit data-structures - Queues

16.2.1 list->queue
------------------


[procedure] (list->queue LIST)
 Returns `LIST' converted into a queue, where the first element of the
list is the same as the first element of the queue. The resulting queue
may share memory with the list and the list should not be modified
after this operation.


File: chicken.info,  Node: Unit data-structures - Queues - make-queue,  Next: Unit data-structures - Queues - queue?,  Prev: Unit data-structures - Queues - list->queue,  Up: Unit data-structures - Queues

16.2.2 make-queue
-----------------


[procedure] (make-queue)
 Returns a newly created queue.


File: chicken.info,  Node: Unit data-structures - Queues - queue?,  Next: Unit data-structures - Queues - queue->list,  Prev: Unit data-structures - Queues - make-queue,  Up: Unit data-structures - Queues

16.2.3 queue?
-------------


[procedure] (queue? X)
 Returns `#t' if `X' is a queue, or `#f' otherwise.


File: chicken.info,  Node: Unit data-structures - Queues - queue->list,  Next: Unit data-structures - Queues - queue-add!,  Prev: Unit data-structures - Queues - queue?,  Up: Unit data-structures - Queues

16.2.4 queue->list
------------------


[procedure] (queue->list QUEUE)
 Returns `QUEUE' converted into a list, where the first element of the
list is the same as the first element of the queue. The resulting list
may share memory with the queue object and should not be modified.


File: chicken.info,  Node: Unit data-structures - Queues - queue-add!,  Next: Unit data-structures - Queues - queue-empty?,  Prev: Unit data-structures - Queues - queue->list,  Up: Unit data-structures - Queues

16.2.5 queue-add!
-----------------


[procedure] (queue-add! QUEUE X)
 Adds `X' to the rear of `QUEUE'.


File: chicken.info,  Node: Unit data-structures - Queues - queue-empty?,  Next: Unit data-structures - Queues - queue-first,  Prev: Unit data-structures - Queues - queue-add!,  Up: Unit data-structures - Queues

16.2.6 queue-empty?
-------------------


[procedure] (queue-empty? QUEUE)
 Returns `#t' if `QUEUE' is empty, or `#f' otherwise.


File: chicken.info,  Node: Unit data-structures - Queues - queue-first,  Next: Unit data-structures - Queues - queue-last,  Prev: Unit data-structures - Queues - queue-empty?,  Up: Unit data-structures - Queues

16.2.7 queue-first
------------------


[procedure] (queue-first QUEUE)
 Returns the first element of `QUEUE'. If `QUEUE' is empty an error is
signaled


File: chicken.info,  Node: Unit data-structures - Queues - queue-last,  Next: Unit data-structures - Queues - queue-remove!,  Prev: Unit data-structures - Queues - queue-first,  Up: Unit data-structures - Queues

16.2.8 queue-last
-----------------


[procedure] (queue-last QUEUE)
 Returns the last element of `QUEUE'. If `QUEUE' is empty an error is
signaled


File: chicken.info,  Node: Unit data-structures - Queues - queue-remove!,  Next: Unit data-structures - Queues - queue-push-back!,  Prev: Unit data-structures - Queues - queue-last,  Up: Unit data-structures - Queues

16.2.9 queue-remove!
--------------------


[procedure] (queue-remove! QUEUE)
 Removes and returns the first element of `QUEUE'. If `QUEUE' is empty
an error is signaled


File: chicken.info,  Node: Unit data-structures - Queues - queue-push-back!,  Next: Unit data-structures - Queues - queue-push-back-list!,  Prev: Unit data-structures - Queues - queue-remove!,  Up: Unit data-structures - Queues

16.2.10 queue-push-back!
------------------------


[procedure] (queue-push-back! QUEUE ITEM)
 Pushes an item into the first position of a queue, i.e. the next
`queue-remove!' will return `ITEM'.


File: chicken.info,  Node: Unit data-structures - Queues - queue-push-back-list!,  Prev: Unit data-structures - Queues - queue-push-back!,  Up: Unit data-structures - Queues

16.2.11 queue-push-back-list!
-----------------------------


[procedure] (queue-push-back-list! QUEUE LIST)
 Pushes the items in item-list back onto the queue, so that `(car
LIST)' becomes the next removable item.


File: chicken.info,  Node: Unit data-structures - Sorting,  Next: Unit data-structures - Random numbers,  Prev: Unit data-structures - Queues,  Up: Unit data-structures

16.3 Sorting
============

* Menu:

* Unit data-structures - Sorting - merge::
* Unit data-structures - Sorting - sort::
* Unit data-structures - Sorting - sorted?::


File: chicken.info,  Node: Unit data-structures - Sorting - merge,  Next: Unit data-structures - Sorting - sort,  Up: Unit data-structures - Sorting

16.3.1 merge
------------


[procedure] (merge LIST1 LIST2 LESS?)
[procedure] (merge! LIST1 LIST2 LESS?)
 Joins two lists in sorted order. `merge!' is the destructive version
of merge. `LESS?  ' should be a procedure of two arguments, that
returns true if the first argument is to be ordered before the second
argument.


File: chicken.info,  Node: Unit data-structures - Sorting - sort,  Next: Unit data-structures - Sorting - sorted?,  Prev: Unit data-structures - Sorting - merge,  Up: Unit data-structures - Sorting

16.3.2 sort
-----------


[procedure] (sort SEQUENCE LESS?)
[procedure] (sort! SEQUENCE LESS?)
 Sort `SEQUENCE', which should be a list or a vector. `sort!' is the
destructive version of sort.


File: chicken.info,  Node: Unit data-structures - Sorting - sorted?,  Prev: Unit data-structures - Sorting - sort,  Up: Unit data-structures - Sorting

16.3.3 sorted?
--------------


[procedure] (sorted? SEQUENCE LESS?)
 Returns true if the list or vector `SEQUENCE' is already sorted.


File: chicken.info,  Node: Unit data-structures - Random numbers,  Next: Unit data-structures - Strings,  Prev: Unit data-structures - Sorting,  Up: Unit data-structures

16.4 Random numbers
===================

* Menu:

* Unit data-structures - Random numbers - random-seed::


File: chicken.info,  Node: Unit data-structures - Random numbers - random-seed,  Up: Unit data-structures - Random numbers

16.4.1 random-seed
------------------


[procedure] (random-seed [SEED])
 Seeds the random number generator with `SEED' (an exact integer) or
`(current-seconds)' if `SEED' is not given.


File: chicken.info,  Node: Unit data-structures - Strings,  Next: Unit data-structures - Combinators,  Prev: Unit data-structures - Random numbers,  Up: Unit data-structures

16.5 Strings
============

* Menu:

* Unit data-structures - Strings - conc::
* Unit data-structures - Strings - ->string::
* Unit data-structures - Strings - string-chop::
* Unit data-structures - Strings - string-chomp::
* Unit data-structures - Strings - string-compare3::
* Unit data-structures - Strings - string-intersperse::
* Unit data-structures - Strings - string-split::
* Unit data-structures - Strings - string-translate::
* Unit data-structures - Strings - string-translate*::
* Unit data-structures - Strings - substring=?::
* Unit data-structures - Strings - substring-index::


File: chicken.info,  Node: Unit data-structures - Strings - conc,  Next: Unit data-structures - Strings - ->string,  Up: Unit data-structures - Strings

16.5.1 conc
-----------


[procedure] (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)) )


File: chicken.info,  Node: Unit data-structures - Strings - ->string,  Next: Unit data-structures - Strings - string-chop,  Prev: Unit data-structures - Strings - conc,  Up: Unit data-structures - Strings

16.5.2 ->string
---------------


[procedure] (->string X)
 Returns a string-representation of `X'.


File: chicken.info,  Node: Unit data-structures - Strings - string-chop,  Next: Unit data-structures - Strings - string-chomp,  Prev: Unit data-structures - Strings - ->string,  Up: Unit data-structures - Strings

16.5.3 string-chop
------------------


[procedure] (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"*)


File: chicken.info,  Node: Unit data-structures - Strings - string-chomp,  Next: Unit data-structures - Strings - string-compare3,  Prev: Unit data-structures - Strings - string-chop,  Up: Unit data-structures - Strings

16.5.4 string-chomp
-------------------


[procedure] (string-chomp STRING [SUFFIX])
 If `STRING' ends with `SUFFIX', then this procedure returns a copy of
its first argument with the suffix removed, otherwise returns `STRING'
unchanged. `SUFFIX' defaults to `"\n"'.


File: chicken.info,  Node: Unit data-structures - Strings - string-compare3,  Next: Unit data-structures - Strings - string-intersperse,  Prev: Unit data-structures - Strings - string-chomp,  Up: Unit data-structures - Strings

16.5.5 string-compare3
----------------------


[procedure] (string-compare3 STRING1 STRING2)
[procedure] (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.


File: chicken.info,  Node: Unit data-structures - Strings - string-intersperse,  Next: Unit data-structures - Strings - string-split,  Prev: Unit data-structures - Strings - string-compare3,  Up: Unit data-structures - Strings

16.5.6 string-intersperse
-------------------------


[procedure] (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"*))


File: chicken.info,  Node: Unit data-structures - Strings - string-split,  Next: Unit data-structures - Strings - string-translate,  Prev: Unit data-structures - Strings - string-intersperse,  Up: Unit data-structures - Strings

16.5.7 string-split
-------------------


[procedure] (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"* *""*)


File: chicken.info,  Node: Unit data-structures - Strings - string-translate,  Next: Unit data-structures - Strings - string-translate*,  Prev: Unit data-structures - Strings - string-split,  Up: Unit data-structures - Strings

16.5.8 string-translate
-----------------------


[procedure] (string-translate STRING FROM [TO])
 Returns a fresh copy of `STRING' with characters matching `FROM'
translated to `TO'.  If `TO' is omitted, then matching characters are
removed. `FROM' and `TO' may be a character, a string or a list. If
both `FROM' and `TO' are strings, then the character at the same
position in `TO' as the matching character in `FROM' is substituted.


File: chicken.info,  Node: Unit data-structures - Strings - string-translate*,  Next: Unit data-structures - Strings - substring=?,  Prev: Unit data-structures - Strings - string-translate,  Up: Unit data-structures - Strings

16.5.9 string-translate*
------------------------


[procedure] (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;/h1&gt;"*


File: chicken.info,  Node: Unit data-structures - Strings - substring=?,  Next: Unit data-structures - Strings - substring-index,  Prev: Unit data-structures - Strings - string-translate*,  Up: Unit data-structures - Strings

16.5.10 substring=?
-------------------


[procedure] (substring=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
[procedure] (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).


File: chicken.info,  Node: Unit data-structures - Strings - substring-index,  Prev: Unit data-structures - Strings - substring=?,  Up: Unit data-structures - Strings

16.5.11 substring-index
-----------------------


[procedure] (substring-index WHICH WHERE [START])
[procedure] (substring-index-ci WHICH WHERE [START])
 Searches for first index in string `WHERE' where string `WHICH'
occurs.  If the optional argument `START' is given, then the search
starts at that index.  `substring-index-ci' is a case-insensitive
version of `substring-index'.


File: chicken.info,  Node: Unit data-structures - Combinators,  Next: Unit data-structures - Binary searching,  Prev: Unit data-structures - Strings,  Up: Unit data-structures

16.6 Combinators
================

* Menu:

* Unit data-structures - Combinators - any?::
* Unit data-structures - Combinators - none?::
* Unit data-structures - Combinators - always?::
* Unit data-structures - Combinators - never?::
* Unit data-structures - Combinators - constantly::
* Unit data-structures - Combinators - complement::
* Unit data-structures - Combinators - compose::
* Unit data-structures - Combinators - conjoin::
* Unit data-structures - Combinators - disjoin::
* Unit data-structures - Combinators - each::
* Unit data-structures - Combinators - flip::
* Unit data-structures - Combinators - identity::
* Unit data-structures - Combinators - project::
* Unit data-structures - Combinators - list-of::
* Unit data-structures - Combinators - noop::
* Unit data-structures - Combinators - o::
* Unit data-structures - Combinators - left-section::
* Unit data-structures - Combinators - right-section::


File: chicken.info,  Node: Unit data-structures - Combinators - any?,  Next: Unit data-structures - Combinators - none?,  Up: Unit data-structures - Combinators

16.6.1 any?
-----------


[procedure] (any? X)
 Ignores its argument and always returns `#t'. This is actually useful
sometimes.


File: chicken.info,  Node: Unit data-structures - Combinators - none?,  Next: Unit data-structures - Combinators - always?,  Prev: Unit data-structures - Combinators - any?,  Up: Unit data-structures - Combinators

16.6.2 none?
------------


[procedure] (none? X)
 Ignores its argument and always returns `#f'. This is actually useful
sometimes.


File: chicken.info,  Node: Unit data-structures - Combinators - always?,  Next: Unit data-structures - Combinators - never?,  Prev: Unit data-structures - Combinators - none?,  Up: Unit data-structures - Combinators

16.6.3 always?
--------------


[procedure] (always? X)
 Ignores its arguments and always returns `#t'. This is actually useful
sometimes.


File: chicken.info,  Node: Unit data-structures - Combinators - never?,  Next: Unit data-structures - Combinators - constantly,  Prev: Unit data-structures - Combinators - always?,  Up: Unit data-structures - Combinators

16.6.4 never?
-------------


[procedure] (never? X)
 Ignores its arguments and always returns `#f'. This is actually useful
sometimes.


File: chicken.info,  Node: Unit data-structures - Combinators - constantly,  Next: Unit data-structures - Combinators - complement,  Prev: Unit data-structures - Combinators - never?,  Up: Unit data-structures - Combinators

16.6.5 constantly
-----------------


[procedure] (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)


File: chicken.info,  Node: Unit data-structures - Combinators - complement,  Next: Unit data-structures - Combinators - compose,  Prev: Unit data-structures - Combinators - constantly,  Up: Unit data-structures - Combinators

16.6.6 complement
-----------------


[procedure] (complement PROC)
 Returns a procedure that returns the boolean inverse of `PROC'.

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


File: chicken.info,  Node: Unit data-structures - Combinators - compose,  Next: Unit data-structures - Combinators - conjoin,  Prev: Unit data-structures - Combinators - complement,  Up: Unit data-structures - Combinators

16.6.7 compose
--------------


[procedure] (compose PROC1 PROC2 ...)
 Returns a procedure that represents the composition of the
argument-procedures `PROC1 PROC2 ...'.

     (compose F G) <*=>* (*lambda* args
                           (call-with-values
                              (*lambda* () (apply G args))
                              F))
`(compose)' is equivalent to `values'.


File: chicken.info,  Node: Unit data-structures - Combinators - conjoin,  Next: Unit data-structures - Combinators - disjoin,  Prev: Unit data-structures - Combinators - compose,  Up: Unit data-structures - Combinators

16.6.8 conjoin
--------------


[procedure] (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


File: chicken.info,  Node: Unit data-structures - Combinators - disjoin,  Next: Unit data-structures - Combinators - each,  Prev: Unit data-structures - Combinators - conjoin,  Up: Unit data-structures - Combinators

16.6.9 disjoin
--------------


[procedure] (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


File: chicken.info,  Node: Unit data-structures - Combinators - each,  Next: Unit data-structures - Combinators - flip,  Prev: Unit data-structures - Combinators - disjoin,  Up: Unit data-structures - Combinators

16.6.10 each
------------


[procedure] (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'.


File: chicken.info,  Node: Unit data-structures - Combinators - flip,  Next: Unit data-structures - Combinators - identity,  Prev: Unit data-structures - Combinators - each,  Up: Unit data-structures - Combinators

16.6.11 flip
------------


[procedure] (flip PROC)
 Returns a two-argument procedure that calls `PROC' with its arguments
swapped:
     (flip PROC) <*=>* (*lambda* (x y) (PROC y x))


File: chicken.info,  Node: Unit data-structures - Combinators - identity,  Next: Unit data-structures - Combinators - project,  Prev: Unit data-structures - Combinators - flip,  Up: Unit data-structures - Combinators

16.6.12 identity
----------------


[procedure] (identity X)
 Returns its sole argument `X'.


File: chicken.info,  Node: Unit data-structures - Combinators - project,  Next: Unit data-structures - Combinators - list-of,  Prev: Unit data-structures - Combinators - identity,  Up: Unit data-structures - Combinators

16.6.13 project
---------------


[procedure] (project N)
 Returns a procedure that returns its `N'th argument (starting from 0).


File: chicken.info,  Node: Unit data-structures - Combinators - list-of,  Next: Unit data-structures - Combinators - noop,  Prev: Unit data-structures - Combinators - project,  Up: Unit data-structures - Combinators

16.6.14 list-of
---------------


[procedure] (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


File: chicken.info,  Node: Unit data-structures - Combinators - noop,  Next: Unit data-structures - Combinators - o,  Prev: Unit data-structures - Combinators - list-of,  Up: Unit data-structures - Combinators

16.6.15 noop
------------


[procedure] (noop X ...)
 Ignores it's arguments, does nothing and returns an unspecified value.


File: chicken.info,  Node: Unit data-structures - Combinators - o,  Next: Unit data-structures - Combinators - left-section,  Prev: Unit data-structures - Combinators - noop,  Up: Unit data-structures - Combinators

16.6.16 o
---------


[procedure] (o PROC ...)
 A single value version of `compose' (slightly faster). `(o)' is
equivalent to `identity'.


File: chicken.info,  Node: Unit data-structures - Combinators - left-section,  Next: Unit data-structures - Combinators - right-section,  Prev: Unit data-structures - Combinators - o,  Up: Unit data-structures - Combinators

16.6.17 left-section
--------------------


[procedure] (left-section PROC ARG0 ...)
 Returns a procedure that partially applies some of its' arguments
starting from the left.

`PROC' a procedure.

   `ARG0 ...' some prefix of the arguments for `PROC'.


File: chicken.info,  Node: Unit data-structures - Combinators - right-section,  Prev: Unit data-structures - Combinators - left-section,  Up: Unit data-structures - Combinators

16.6.18 right-section
---------------------


[procedure] (right-section PROC ARG0 ...)
 Returns a procedure that partially applies some of its' arguments
starting from the right.

`PROC' a procedure.

   `ARG0 ...' some reversed suffix of the arguments for `PROC'.


File: chicken.info,  Node: Unit data-structures - Binary searching,  Prev: Unit data-structures - Combinators,  Up: Unit data-structures

16.7 Binary searching
=====================

* Menu:

* Unit data-structures - Binary searching - binary-search::


File: chicken.info,  Node: Unit data-structures - Binary searching - binary-search,  Up: Unit data-structures - Binary searching

16.7.1 binary-search
--------------------


[procedure] (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. Returns
the index of the found value or `#f' otherwise.

Previous: *Note Unit eval: Unit eval.

   Next: *Note Unit ports: Unit ports.


File: chicken.info,  Node: Unit ports,  Next: Unit files,  Prev: Unit data-structures,  Up: Top

17 Unit ports
*************

* Menu:

* Unit ports - Input/output port extensions::
* Unit ports - String-port extensions::
* Unit ports - Port iterators::
* Unit ports - Funky ports::

   This unit contains various extended port definitions. This unit is
used by default, unless the program is compiled with the
`-explicit-use' option.


File: chicken.info,  Node: Unit ports - Input/output port extensions,  Next: Unit ports - String-port extensions,  Up: Unit ports

17.1 Input/output port extensions
=================================

* Menu:

* Unit ports - Input/output port extensions - with-output-to-port::
* Unit ports - Input/output port extensions - make-input-port::
* Unit ports - Input/output port extensions - make-output-port::
* Unit ports - Input/output port extensions - with-error-output-to-port::
* Unit ports - Input/output port extensions - with-input-from-port::


File: chicken.info,  Node: Unit ports - Input/output port extensions - with-output-to-port,  Next: Unit ports - Input/output port extensions - make-input-port,  Up: Unit ports - Input/output port extensions

17.1.1 with-output-to-port
--------------------------


[procedure] (with-output-to-port PORT THUNK)
 Call procedure `THUNK' with the current output-port temporarily bound
to `PORT'.


File: chicken.info,  Node: Unit ports - Input/output port extensions - make-input-port,  Next: Unit ports - Input/output port extensions - make-output-port,  Prev: Unit ports - Input/output port extensions - with-output-to-port,  Up: Unit ports - Input/output port extensions

17.1.2 make-input-port
----------------------


[procedure] (make-input-port READ READY? CLOSE [PEEK])
 Returns a custom input port. Common operations on this port are
handled by the given parameters, which should be procedures of no
arguments. `READ' is called when the next character is to be read and
should return a character or `#!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).


File: chicken.info,  Node: Unit ports - Input/output port extensions - make-output-port,  Next: Unit ports - Input/output port extensions - with-error-output-to-port,  Prev: Unit ports - Input/output port extensions - make-input-port,  Up: Unit ports - Input/output port extensions

17.1.3 make-output-port
-----------------------


[procedure] (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.


File: chicken.info,  Node: Unit ports - Input/output port extensions - with-error-output-to-port,  Next: Unit ports - Input/output port extensions - with-input-from-port,  Prev: Unit ports - Input/output port extensions - make-output-port,  Up: Unit ports - Input/output port extensions

17.1.4 with-error-output-to-port
--------------------------------


[procedure] (with-error-output-to-port PORT THUNK)
 Call procedure `THUNK' with the current error output-port temporarily
bound to `PORT'.


File: chicken.info,  Node: Unit ports - Input/output port extensions - with-input-from-port,  Prev: Unit ports - Input/output port extensions - with-error-output-to-port,  Up: Unit ports - Input/output port extensions

17.1.5 with-input-from-port
---------------------------


[procedure] (with-input-from-port PORT THUNK)
 Call procedure `THUNK' with the current input-port temporarily bound
to `PORT'.


File: chicken.info,  Node: Unit ports - String-port extensions,  Next: Unit ports - Port iterators,  Prev: Unit ports - Input/output port extensions,  Up: Unit ports

17.2 String-port extensions
===========================

* Menu:

* Unit ports - String-port extensions - call-with-input-string::
* Unit ports - String-port extensions - call-with-output-string::
* Unit ports - String-port extensions - with-input-from-string::
* Unit ports - String-port extensions - with-output-to-string::


File: chicken.info,  Node: Unit ports - String-port extensions - call-with-input-string,  Next: Unit ports - String-port extensions - call-with-output-string,  Up: Unit ports - String-port extensions

17.2.1 call-with-input-string
-----------------------------


[procedure] (call-with-input-string STRING PROC)
 Calls the procedure `PROC' with a single argument that is a
string-input-port with the contents of `STRING'.


File: chicken.info,  Node: Unit ports - String-port extensions - call-with-output-string,  Next: Unit ports - String-port extensions - with-input-from-string,  Prev: Unit ports - String-port extensions - call-with-input-string,  Up: Unit ports - String-port extensions

17.2.2 call-with-output-string
------------------------------


[procedure] (call-with-output-string PROC)
 Calls the procedure `PROC' with a single argument that is a
string-output-port.  Returns the accumulated output-string.


File: chicken.info,  Node: Unit ports - String-port extensions - with-input-from-string,  Next: Unit ports - String-port extensions - with-output-to-string,  Prev: Unit ports - String-port extensions - call-with-output-string,  Up: Unit ports - String-port extensions

17.2.3 with-input-from-string
-----------------------------


[procedure] (with-input-from-string STRING THUNK)
 Call procedure `THUNK' with the current input-port temporarily bound
to an input-string-port with the contents of `STRING'.


File: chicken.info,  Node: Unit ports - String-port extensions - with-output-to-string,  Prev: Unit ports - String-port extensions - with-input-from-string,  Up: Unit ports - String-port extensions

17.2.4 with-output-to-string
----------------------------


[procedure] (with-output-to-string THUNK)
 Call procedure `THUNK' with the current output-port temporarily bound
to a string-output-port and return the accumulated output string.


File: chicken.info,  Node: Unit ports - Port iterators,  Next: Unit ports - Funky ports,  Prev: Unit ports - String-port extensions,  Up: Unit ports

17.3 Port iterators
===================

* Menu:

* Unit ports - Port iterators - port-for-each::
* Unit ports - Port iterators - port-map::
* Unit ports - Port iterators - port-fold::


File: chicken.info,  Node: Unit ports - Port iterators - port-for-each,  Next: Unit ports - Port iterators - port-map,  Up: Unit ports - Port iterators

17.3.1 port-for-each
--------------------


[procedure] (port-for-each FN THUNK)
 Apply `FN' to successive results of calling the zero argument
procedure `THUNK' until it returns `#!eof', discarding the results.


File: chicken.info,  Node: Unit ports - Port iterators - port-map,  Next: Unit ports - Port iterators - port-fold,  Prev: Unit ports - Port iterators - port-for-each,  Up: Unit ports - Port iterators

17.3.2 port-map
---------------


[procedure] (port-map FN THUNK)
 Apply `FN' to successive results of calling the zero argument
procedure `THUNK' until it returns `#!eof', returning a list of the
collected results.


File: chicken.info,  Node: Unit ports - Port iterators - port-fold,  Prev: Unit ports - Port iterators - port-map,  Up: Unit ports - Port iterators

17.3.3 port-fold
----------------


[procedure] (port-map FN ACC THUNK)
 Apply `FN' to successive results of calling the zero argument
procedure `THUNK', passing the `ACC' value as the second argument. The
`FN' result becomes the new `ACC' value. When `THUNK' returns `#!eof',
the last `FN' result is returned.


File: chicken.info,  Node: Unit ports - Funky ports,  Prev: Unit ports - Port iterators,  Up: Unit ports

17.4 Funky ports
================

* Menu:

* Unit ports - Funky ports - make-broadcast-port::
* Unit ports - Funky ports - make-concatenated-port::


File: chicken.info,  Node: Unit ports - Funky ports - make-broadcast-port,  Next: Unit ports - Funky ports - make-concatenated-port,  Up: Unit ports - Funky ports

17.4.1 make-broadcast-port
--------------------------


[procedure] (make-broadcast-port PORT ...)
 Returns a custom output port that emits everything written into it to
the ports given as `PORT ...'. Closing the broadcast port does not
close any of the argument ports.


File: chicken.info,  Node: Unit ports - Funky ports - make-concatenated-port,  Prev: Unit ports - Funky ports - make-broadcast-port,  Up: Unit ports - Funky ports

17.4.2 make-concatenated-port
-----------------------------


[procedure] (make-concatenated-port PORT1 PORT2 ...)
 Returns a custom input port that reads its input from `PORT1', until
it is empty, then from `PORT2' and so on. Closing the concatenated port
does not close any of the argument ports.

Previous: *Note Unit data-structures: Unit data-structures.

   Next: *Note Unit files: Unit files.


File: chicken.info,  Node: Unit files,  Next: Unit extras,  Prev: Unit ports,  Up: Top

18 Unit files
*************

* Menu:

* Unit files - Pathname operations::
* Unit files - Temporary files::
* Unit files - Deleting a file without signalling an error::
* Unit files - File move/copy::

   This unit contains file- and pathname-oriented procedures. It uses
the `regex' unit.


File: chicken.info,  Node: Unit files - Pathname operations,  Next: Unit files - Temporary files,  Up: Unit files

18.1 Pathname operations
========================

* Menu:

* Unit files - Pathname operations - absolute-pathname?::
* Unit files - Pathname operations - decompose-pathname::
* Unit files - Pathname operations - make-pathname::
* Unit files - Pathname operations - make-absolute-pathname::
* Unit files - Pathname operations - pathname-directory::
* Unit files - Pathname operations - pathname-file::
* Unit files - Pathname operations - pathname-extension::
* Unit files - Pathname operations - pathname-replace-directory::
* Unit files - Pathname operations - pathname-replace-file::
* Unit files - Pathname operations - pathname-replace-extension::
* Unit files - Pathname operations - pathname-strip-directory::
* Unit files - Pathname operations - pathname-strip-extension::
* Unit files - Pathname operations - directory-null?::


File: chicken.info,  Node: Unit files - Pathname operations - absolute-pathname?,  Next: Unit files - Pathname operations - decompose-pathname,  Up: Unit files - Pathname operations

18.1.1 absolute-pathname?
-------------------------


[procedure] (absolute-pathname? PATHNAME)
 Returns `#t' if the string `PATHNAME' names an absolute pathname, and
returns `#f' otherwise.


File: chicken.info,  Node: Unit files - Pathname operations - decompose-pathname,  Next: Unit files - Pathname operations - make-pathname,  Prev: Unit files - Pathname operations - absolute-pathname?,  Up: Unit files - Pathname operations

18.1.2 decompose-pathname
-------------------------


[procedure] (decompose-pathname PATHNAME)
 Returns three values: the directory-, filename- and
extension-components of the file named by the string `PATHNAME'. For
any component that is not contained in `PATHNAME', `#f' is returned.


File: chicken.info,  Node: Unit files - Pathname operations - make-pathname,  Next: Unit files - Pathname operations - make-absolute-pathname,  Prev: Unit files - Pathname operations - decompose-pathname,  Up: Unit files - Pathname operations

18.1.3 make-pathname
--------------------


File: chicken.info,  Node: Unit files - Pathname operations - make-absolute-pathname,  Next: Unit files - Pathname operations - pathname-directory,  Prev: Unit files - Pathname operations - make-pathname,  Up: Unit files - Pathname operations

18.1.4 make-absolute-pathname
-----------------------------


[procedure] (make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
[procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
 Returns a string that names the file with the components `DIRECTORY,
FILENAME' and (optionally) `EXTENSION' with `SEPARATOR' being the
directory separation indicator (usually `/' on UNIX systems and `\' on
Windows, defaulting to whatever platform this is running on).
`DIRECTORY' can be `#f' (meaning no directory component), a string or a
list of strings. `FILENAME' and `EXTENSION' should be strings or `#f'.
`make-absolute-pathname' returns always an absolute pathname.


File: chicken.info,  Node: Unit files - Pathname operations - pathname-directory,  Next: Unit files - Pathname operations - pathname-file,  Prev: Unit files - Pathname operations - make-absolute-pathname,  Up: Unit files - Pathname operations

18.1.5 pathname-directory
-------------------------


[procedure] (pathname-directory PATHNAME)


File: chicken.info,  Node: Unit files - Pathname operations - pathname-file,  Next: Unit files - Pathname operations - pathname-extension,  Prev: Unit files - Pathname operations - pathname-directory,  Up: Unit files - Pathname operations

18.1.6 pathname-file
--------------------


[procedure] (pathname-file PATHNAME)


File: chicken.info,  Node: Unit files - Pathname operations - pathname-extension,  Next: Unit files - Pathname operations - pathname-replace-directory,  Prev: Unit files - Pathname operations - pathname-file,  Up: Unit files - Pathname operations

18.1.7 pathname-extension
-------------------------


[procedure] (pathname-extension PATHNAME)
 Accessors for the components of `PATHNAME'. If the pathname does not
contain the accessed component, then `#f' is returned.


File: chicken.info,  Node: Unit files - Pathname operations - pathname-replace-directory,  Next: Unit files - Pathname operations - pathname-replace-file,  Prev: Unit files - Pathname operations - pathname-extension,  Up: Unit files - Pathname operations

18.1.8 pathname-replace-directory
---------------------------------


[procedure] (pathname-replace-directory PATHNAME DIRECTORY)


File: chicken.info,  Node: Unit files - Pathname operations - pathname-replace-file,  Next: Unit files - Pathname operations - pathname-replace-extension,  Prev: Unit files - Pathname operations - pathname-replace-directory,  Up: Unit files - Pathname operations

18.1.9 pathname-replace-file
----------------------------


[procedure] (pathname-replace-file PATHNAME FILENAME)


File: chicken.info,  Node: Unit files - Pathname operations - pathname-replace-extension,  Next: Unit files - Pathname operations - pathname-strip-directory,  Prev: Unit files - Pathname operations - pathname-replace-file,  Up: Unit files - Pathname operations

18.1.10 pathname-replace-extension
----------------------------------


[procedure] (pathname-replace-extension PATHNAME EXTENSION)
 Return a new pathname with the specified component of `PATHNAME'
replaced by a new value.


File: chicken.info,  Node: Unit files - Pathname operations - pathname-strip-directory,  Next: Unit files - Pathname operations - pathname-strip-extension,  Prev: Unit files - Pathname operations - pathname-replace-extension,  Up: Unit files - Pathname operations

18.1.11 pathname-strip-directory
--------------------------------


[procedure] (pathname-strip-directory PATHNAME)


File: chicken.info,  Node: Unit files - Pathname operations - pathname-strip-extension,  Next: Unit files - Pathname operations - directory-null?,  Prev: Unit files - Pathname operations - pathname-strip-directory,  Up: Unit files - Pathname operations

18.1.12 pathname-strip-extension
--------------------------------


[procedure] (pathname-strip-extension PATHNAME)
 Return a new pathname with the specified component of `PATHNAME'
stripped.


File: chicken.info,  Node: Unit files - Pathname operations - directory-null?,  Prev: Unit files - Pathname operations - pathname-strip-extension,  Up: Unit files - Pathname operations

18.1.13 directory-null?
-----------------------


[procedure] (directory-null? DIRECTORY)
 Does the `DIRECTORY' consist only of path separators and the period?

`DIRECTORY' may be a string or a list of strings.


File: chicken.info,  Node: Unit files - Temporary files,  Next: Unit files - Deleting a file without signalling an error,  Prev: Unit files - Pathname operations,  Up: Unit files

18.2 Temporary files
====================

* Menu:

* Unit files - Temporary files - create-temporary-file::


File: chicken.info,  Node: Unit files - Temporary files - create-temporary-file,  Up: Unit files - Temporary files

18.2.1 create-temporary-file
----------------------------


[procedure] (create-temporary-file [EXTENSION])
 Creates an empty temporary file and returns its pathname. If
`EXTENSION' is not given, then `.tmp' is used. If the environment
variable `TMPDIR, TEMP' or `TMP' is set, then the pathname names a file
in that directory.


File: chicken.info,  Node: Unit files - Deleting a file without signalling an error,  Next: Unit files - File move/copy,  Prev: Unit files - Temporary files,  Up: Unit files

18.3 Deleting a file without signalling an error
================================================

* Menu:

* Unit files - Deleting a file without signalling an error - delete-file*::


File: chicken.info,  Node: Unit files - Deleting a file without signalling an error - delete-file*,  Up: Unit files - Deleting a file without signalling an error

18.3.1 delete-file*
-------------------


[procedure] (delete-file* FILENAME)
 If the file `FILENAME' exists, it is deleted and `#t' is returned.  If
the file does not exist, nothing happens and `#f' is returned.


File: chicken.info,  Node: Unit files - File move/copy,  Prev: Unit files - Deleting a file without signalling an error,  Up: Unit files

18.4 File move/copy
===================

* Menu:

* Unit files - File move/copy - file-copy::
* Unit files - File move/copy - file-move::


File: chicken.info,  Node: Unit files - File move/copy - file-copy,  Next: Unit files - File move/copy - file-move,  Up: Unit files - File move/copy

18.4.1 file-copy
----------------


[procedure] (file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
 Copies `ORIGFILE' (a string denoting some filename) to `NEWFILE',
`BLOCKSIZE' bytes at a time.  `BLOCKSIZE' defaults to 1024, and must be
a positive integer.  Returns the number of bytes copied on success, or
errors on failure.  `CLOBBER' determines the behaviour of `file-copy'
when `NEWFILE' is already extant.  When set to `#f' (default), an error
is signalled.  When set to any other value, `NEWFILE' is overwritten.
`file-copy' will work across filesystems and devices and is not
platform-dependent.


File: chicken.info,  Node: Unit files - File move/copy - file-move,  Prev: Unit files - File move/copy - file-copy,  Up: Unit files - File move/copy

18.4.2 file-move
----------------


[procedure] (file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
 Moves `ORIGFILE' (a string denoting some filename) to `NEWFILE', with
the same semantics as `file-copy', above.  `file-move' is safe across
filesystems and devices (unlike `file-rename').  It is possible for an
error to be signalled despite partial success if `NEWFILE' could be
created and fully written but removing `ORIGFILE' fails.

Previous: *Note Unit ports: Unit ports.

   Next: *Note Unit extras: Unit extras.


File: chicken.info,  Node: Unit extras,  Next: Unit srfi-1,  Prev: Unit files,  Up: Top

19 Unit extras
**************

* Menu:

* Unit extras - Formatted output::
* Unit extras - Random numbers::
* Unit extras - Input/Output extensions::

   This unit contains a collection of useful utility definitions.  This
unit is used by default, unless the program is compiled with the
`-explicit-use' option.


File: chicken.info,  Node: Unit extras - Formatted output,  Next: Unit extras - Random numbers,  Up: Unit extras

19.1 Formatted output
=====================

* Menu:

* Unit extras - Formatted output - printf::
* Unit extras - Formatted output - fprintf::
* Unit extras - Formatted output - sprintf::
* Unit extras - Formatted output - format::


File: chicken.info,  Node: Unit extras - Formatted output - printf,  Next: Unit extras - Formatted output - fprintf,  Up: Unit extras - Formatted output

19.1.1 printf
-------------


File: chicken.info,  Node: Unit extras - Formatted output - fprintf,  Next: Unit extras - Formatted output - sprintf,  Prev: Unit extras - Formatted output - printf,  Up: Unit extras - Formatted output

19.1.2 fprintf
--------------


File: chicken.info,  Node: Unit extras - Formatted output - sprintf,  Next: Unit extras - Formatted output - format,  Prev: Unit extras - Formatted output - fprintf,  Up: Unit extras - Formatted output

19.1.3 sprintf
--------------


[procedure] (fprintf PORT FORMATSTRING ARG ...)
[procedure] (printf FORMATSTRING ARG ...)
[procedure] (sprintf FORMATSTRING ARG ...)
 Simple formatted output to a given port (`fprintf'), the value of
`(current-output-port)' (`printf'), or a string (`sprintf').  The
`FORMATSTRING' can contain any sequence of characters.  There must be
at least as many `ARG' arguments given as there are format directives
that require an argument in `FORMATSTRING'.  Extra `ARG' arguments are
ignored.  The character `~' prefixes special formatting directives:

<table> <tr><td> ~% write newline character </td></tr><tr><td> ~N the
same as `~%' </td></tr><tr><td> ~S write the next argument
</td></tr><tr><td> ~A display the next argument </td></tr><tr><td> ~\n
skip all whitespace in the format-string until the next non-whitespace
character </td></tr><tr><td> ~B write the next argument as a binary
number </td></tr><tr><td> ~O write the next argument as an octal number
</td></tr><tr><td> ~X write the next argument as a hexadecimal number
</td></tr><tr><td> ~C write the next argument as a character
</td></tr><tr><td> ~~ display `~' </td></tr><tr><td> ~! flush all
pending output </td></tr><tr><td> ~? invoke formatted output routine
recursively with the next two arguments as format-string and list of
parameters </td></tr></table>


File: chicken.info,  Node: Unit extras - Formatted output - format,  Prev: Unit extras - Formatted output - sprintf,  Up: Unit extras - Formatted output

19.1.4 format
-------------


[procedure] (format [DESTINATION] FORMATSTRING ARG ...)
 The parameters  `FORMATSTRING' and `ARG ...' are as for
(`printf'/`sprintf'/`fprintf').

The optional `DESTINATION', when supplied, performs a (`sprintf') for a
`#f', a (`printf') for a `#t', and a (`fprintf') for an output-port.
When missing a (`sprintf') is performed.


File: chicken.info,  Node: Unit extras - Random numbers,  Next: Unit extras - Input/Output extensions,  Prev: Unit extras - Formatted output,  Up: Unit extras

19.2 Random numbers
===================

* Menu:

* Unit extras - Random numbers - random-seed::
* Unit extras - Random numbers - random::
* Unit extras - Random numbers - randomize::


File: chicken.info,  Node: Unit extras - Random numbers - random-seed,  Next: Unit extras - Random numbers - random,  Up: Unit extras - Random numbers

19.2.1 random-seed
------------------


[procedure] (random-seed [SEED])
 Seeds the random number generator with `SEED' (an exact integer) or
`(current-seconds)' if `SEED' is not given.


File: chicken.info,  Node: Unit extras - Random numbers - random,  Next: Unit extras - Random numbers - randomize,  Prev: Unit extras - Random numbers - random-seed,  Up: Unit extras - Random numbers

19.2.2 random
-------------


[procedure] (random N)
 Returns an exact random integer from 0 to `N'-1.


File: chicken.info,  Node: Unit extras - Random numbers - randomize,  Prev: Unit extras - Random numbers - random,  Up: Unit extras - Random numbers

19.2.3 randomize
----------------


[procedure] (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.


File: chicken.info,  Node: Unit extras - Input/Output extensions,  Prev: Unit extras - Random numbers,  Up: Unit extras

19.3 Input/Output extensions
============================

* Menu:

* Unit extras - Input/Output extensions - pretty-print::
* Unit extras - Input/Output extensions - pretty-print-width::
* Unit extras - Input/Output extensions - read-byte::
* Unit extras - Input/Output extensions - write-byte::
* Unit extras - Input/Output extensions - read-file::
* Unit extras - Input/Output extensions - read-line::
* Unit extras - Input/Output extensions - write-line::
* Unit extras - Input/Output extensions - read-lines::
* Unit extras - Input/Output extensions - read-string::
* Unit extras - Input/Output extensions - read-string!::
* Unit extras - Input/Output extensions - write-string::
* Unit extras - Input/Output extensions - read-token::


File: chicken.info,  Node: Unit extras - Input/Output extensions - pretty-print,  Next: Unit extras - Input/Output extensions - pretty-print-width,  Up: Unit extras - Input/Output extensions

19.3.1 pretty-print
-------------------


[procedure] (pretty-print EXP [PORT])
[procedure] (pp EXP [PORT])
 Print expression nicely formatted. `PORT' defaults to the value of
`(current-output-port)'.


File: chicken.info,  Node: Unit extras - Input/Output extensions - pretty-print-width,  Next: Unit extras - Input/Output extensions - read-byte,  Prev: Unit extras - Input/Output extensions - pretty-print,  Up: Unit extras - Input/Output extensions

19.3.2 pretty-print-width
-------------------------

(Parameter) Specifies the maximal line-width for pretty printing, after
which line wrap will occur.


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-byte,  Next: Unit extras - Input/Output extensions - write-byte,  Prev: Unit extras - Input/Output extensions - pretty-print-width,  Up: Unit extras - Input/Output extensions

19.3.3 read-byte
----------------


File: chicken.info,  Node: Unit extras - Input/Output extensions - write-byte,  Next: Unit extras - Input/Output extensions - read-file,  Prev: Unit extras - Input/Output extensions - read-byte,  Up: Unit extras - Input/Output extensions

19.3.4 write-byte
-----------------


[procedure] (read-byte [PORT])
[procedure] (write-byte BYTE [PORT])
 Read/write a byte to the port given in `PORT', which default to the
values of `(current-input-port)' and `(current-output-port)',
respectively.


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-file,  Next: Unit extras - Input/Output extensions - read-line,  Prev: Unit extras - Input/Output extensions - write-byte,  Up: Unit extras - Input/Output extensions

19.3.5 read-file
----------------


[procedure] (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.


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-line,  Next: Unit extras - Input/Output extensions - write-line,  Prev: Unit extras - Input/Output extensions - read-file,  Up: Unit extras - Input/Output extensions

19.3.6 read-line
----------------


File: chicken.info,  Node: Unit extras - Input/Output extensions - write-line,  Next: Unit extras - Input/Output extensions - read-lines,  Prev: Unit extras - Input/Output extensions - read-line,  Up: Unit extras - Input/Output extensions

19.3.7 write-line
-----------------


[procedure] (read-line [PORT [LIMIT]])
[procedure] (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. `read-line' returns a string
without the terminating newline and `write-line' adds a terminating
newline  before outputting.


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-lines,  Next: Unit extras - Input/Output extensions - read-string,  Prev: Unit extras - Input/Output extensions - write-line,  Up: Unit extras - Input/Output extensions

19.3.8 read-lines
-----------------


[procedure] (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. Returns a list of strings, each string representing a line read,
not including any line separation character(s).


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-string,  Next: Unit extras - Input/Output extensions - read-string!,  Prev: Unit extras - Input/Output extensions - read-lines,  Up: Unit extras - Input/Output extensions

19.3.9 read-string
------------------


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-string!,  Next: Unit extras - Input/Output extensions - write-string,  Prev: Unit extras - Input/Output extensions - read-string,  Up: Unit extras - Input/Output extensions

19.3.10 read-string!
--------------------


File: chicken.info,  Node: Unit extras - Input/Output extensions - write-string,  Next: Unit extras - Input/Output extensions - read-token,  Prev: Unit extras - Input/Output extensions - read-string!,  Up: Unit extras - Input/Output extensions

19.3.11 write-string
--------------------


[procedure] (read-string [NUM [PORT]])
[procedure] (read-string! NUM STRING [PORT [START]])
[procedure] (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. `read-string!' reads destructively into the given
`STRING' argument, but never more characters that would fit into
`STRING'. If `START' is given, then the read characters are stored
starting at that position. `read-string!' returns the actual number of
characters read.


File: chicken.info,  Node: Unit extras - Input/Output extensions - read-token,  Prev: Unit extras - Input/Output extensions - write-string,  Up: Unit extras - Input/Output extensions

19.3.12 read-token
------------------


[procedure] (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.

Previous: *Note Unit files: Unit files.

   Next: *Note Unit srfi-1: Unit srfi-1.


File: chicken.info,  Node: Unit srfi-1,  Next: Unit srfi-4,  Prev: Unit extras,  Up: Top

20 Unit srfi-1
**************

List library, see the documentation for SRFI-1
(http://srfi.schemers.org/srfi-1/srfi-1.html)

   Previous: *Note Unit extras: Unit extras.

   Next: *Note Unit srfi-4: Unit srfi-4.


File: chicken.info,  Node: Unit srfi-4,  Next: Unit srfi-13,  Prev: Unit srfi-1,  Up: Top

21 Unit srfi-4
**************

* Menu:

* Unit srfi-4 - make-XXXvector::
* Unit srfi-4 - u8vector->blob::
* Unit srfi-4 - s8vector->blob::
* Unit srfi-4 - u16vector->blob::
* Unit srfi-4 - s16vector->blob::
* Unit srfi-4 - u32vector->blob::
* Unit srfi-4 - s32vector->blob::
* Unit srfi-4 - f32vector->blob::
* Unit srfi-4 - f64vector->blob::
* Unit srfi-4 - u8vector->blob/shared::
* Unit srfi-4 - s8vector->blob/shared::
* Unit srfi-4 - u16vector->blob/shared::
* Unit srfi-4 - s16vector->blob/shared::
* Unit srfi-4 - u32vector->blob/shared::
* Unit srfi-4 - s32vector->blob/shared::
* Unit srfi-4 - f32vector->blob/shared::
* Unit srfi-4 - f64vector->blob/shared::
* Unit srfi-4 - blob->u8vector::
* Unit srfi-4 - blob->s8vector::
* Unit srfi-4 - blob->u16vector::
* Unit srfi-4 - blob->s16vector::
* Unit srfi-4 - blob->u32vector::
* Unit srfi-4 - blob->s32vector::
* Unit srfi-4 - blob->f32vector::
* Unit srfi-4 - blob->f64vector::
* Unit srfi-4 - blob->u8vector/shared::
* Unit srfi-4 - blob->s8vector/shared::
* Unit srfi-4 - blob->u16vector/shared::
* Unit srfi-4 - blob->s16vector/shared::
* Unit srfi-4 - blob->u32vector/shared::
* Unit srfi-4 - blob->s32vector/shared::
* Unit srfi-4 - blob->f32vector/shared::
* Unit srfi-4 - blob->f64vector/shared::
* Unit srfi-4 - subu8vector::
* Unit srfi-4 - subu16vector::
* Unit srfi-4 - subu32vector::
* Unit srfi-4 - subs8vector::
* Unit srfi-4 - subs16vector::
* Unit srfi-4 - subs32vector::
* Unit srfi-4 - subf32vector::
* Unit srfi-4 - subf64vector::
* Unit srfi-4 - read-u8vector::
* Unit srfi-4 - read-u8vector!::
* Unit srfi-4 - write-u8vector::

   Homogeneous numeric vectors, see the documentation for SRFI-4
(http://srfi.schemers.org/srfi-4/srfi-4.html) 64-bit integer vectors
(`u64vector' and `s64vector' are not supported.

   The basic constructor procedures for number vectors are extended to
allow allocating the storage in non garbage collected memory:


File: chicken.info,  Node: Unit srfi-4 - make-XXXvector,  Next: Unit srfi-4 - u8vector->blob,  Up: Unit srfi-4

21.1 make-XXXvector
===================


[procedure] (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.

Additionally, the following procedures are provided:


File: chicken.info,  Node: Unit srfi-4 - u8vector->blob,  Next: Unit srfi-4 - s8vector->blob,  Prev: Unit srfi-4 - make-XXXvector,  Up: Unit srfi-4

21.2 u8vector->blob
===================


File: chicken.info,  Node: Unit srfi-4 - s8vector->blob,  Next: Unit srfi-4 - u16vector->blob,  Prev: Unit srfi-4 - u8vector->blob,  Up: Unit srfi-4

21.3 s8vector->blob
===================


File: chicken.info,  Node: Unit srfi-4 - u16vector->blob,  Next: Unit srfi-4 - s16vector->blob,  Prev: Unit srfi-4 - s8vector->blob,  Up: Unit srfi-4

21.4 u16vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - s16vector->blob,  Next: Unit srfi-4 - u32vector->blob,  Prev: Unit srfi-4 - u16vector->blob,  Up: Unit srfi-4

21.5 s16vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - u32vector->blob,  Next: Unit srfi-4 - s32vector->blob,  Prev: Unit srfi-4 - s16vector->blob,  Up: Unit srfi-4

21.6 u32vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - s32vector->blob,  Next: Unit srfi-4 - f32vector->blob,  Prev: Unit srfi-4 - u32vector->blob,  Up: Unit srfi-4

21.7 s32vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - f32vector->blob,  Next: Unit srfi-4 - f64vector->blob,  Prev: Unit srfi-4 - s32vector->blob,  Up: Unit srfi-4

21.8 f32vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - f64vector->blob,  Next: Unit srfi-4 - u8vector->blob/shared,  Prev: Unit srfi-4 - f32vector->blob,  Up: Unit srfi-4

21.9 f64vector->blob
====================


File: chicken.info,  Node: Unit srfi-4 - u8vector->blob/shared,  Next: Unit srfi-4 - s8vector->blob/shared,  Prev: Unit srfi-4 - f64vector->blob,  Up: Unit srfi-4

21.10 u8vector->blob/shared
===========================


File: chicken.info,  Node: Unit srfi-4 - s8vector->blob/shared,  Next: Unit srfi-4 - u16vector->blob/shared,  Prev: Unit srfi-4 - u8vector->blob/shared,  Up: Unit srfi-4

21.11 s8vector->blob/shared
===========================


File: chicken.info,  Node: Unit srfi-4 - u16vector->blob/shared,  Next: Unit srfi-4 - s16vector->blob/shared,  Prev: Unit srfi-4 - s8vector->blob/shared,  Up: Unit srfi-4

21.12 u16vector->blob/shared
============================


File: chicken.info,  Node: Unit srfi-4 - s16vector->blob/shared,  Next: Unit srfi-4 - u32vector->blob/shared,  Prev: Unit srfi-4 - u16vector->blob/shared,  Up: Unit srfi-4

21.13 s16vector->blob/shared
============================


File: chicken.info,  Node: Unit srfi-4 - u32vector->blob/shared,  Next: Unit srfi-4 - s32vector->blob/shared,  Prev: Unit srfi-4 - s16vector->blob/shared,  Up: Unit srfi-4

21.14 u32vector->blob/shared
============================


File: chicken.info,  Node: Unit srfi-4 - s32vector->blob/shared,  Next: Unit srfi-4 - f32vector->blob/shared,  Prev: Unit srfi-4 - u32vector->blob/shared,  Up: Unit srfi-4

21.15 s32vector->blob/shared
============================


File: chicken.info,  Node: Unit srfi-4 - f32vector->blob/shared,  Next: Unit srfi-4 - f64vector->blob/shared,  Prev: Unit srfi-4 - s32vector->blob/shared,  Up: Unit srfi-4

21.16 f32vector->blob/shared
============================


File: chicken.info,  Node: Unit srfi-4 - f64vector->blob/shared,  Next: Unit srfi-4 - blob->u8vector,  Prev: Unit srfi-4 - f32vector->blob/shared,  Up: Unit srfi-4

21.17 f64vector->blob/shared
============================


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


File: chicken.info,  Node: Unit srfi-4 - blob->u8vector,  Next: Unit srfi-4 - blob->s8vector,  Prev: Unit srfi-4 - f64vector->blob/shared,  Up: Unit srfi-4

21.18 blob->u8vector
====================


File: chicken.info,  Node: Unit srfi-4 - blob->s8vector,  Next: Unit srfi-4 - blob->u16vector,  Prev: Unit srfi-4 - blob->u8vector,  Up: Unit srfi-4

21.19 blob->s8vector
====================


File: chicken.info,  Node: Unit srfi-4 - blob->u16vector,  Next: Unit srfi-4 - blob->s16vector,  Prev: Unit srfi-4 - blob->s8vector,  Up: Unit srfi-4

21.20 blob->u16vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->s16vector,  Next: Unit srfi-4 - blob->u32vector,  Prev: Unit srfi-4 - blob->u16vector,  Up: Unit srfi-4

21.21 blob->s16vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->u32vector,  Next: Unit srfi-4 - blob->s32vector,  Prev: Unit srfi-4 - blob->s16vector,  Up: Unit srfi-4

21.22 blob->u32vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->s32vector,  Next: Unit srfi-4 - blob->f32vector,  Prev: Unit srfi-4 - blob->u32vector,  Up: Unit srfi-4

21.23 blob->s32vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->f32vector,  Next: Unit srfi-4 - blob->f64vector,  Prev: Unit srfi-4 - blob->s32vector,  Up: Unit srfi-4

21.24 blob->f32vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->f64vector,  Next: Unit srfi-4 - blob->u8vector/shared,  Prev: Unit srfi-4 - blob->f32vector,  Up: Unit srfi-4

21.25 blob->f64vector
=====================


File: chicken.info,  Node: Unit srfi-4 - blob->u8vector/shared,  Next: Unit srfi-4 - blob->s8vector/shared,  Prev: Unit srfi-4 - blob->f64vector,  Up: Unit srfi-4

21.26 blob->u8vector/shared
===========================


File: chicken.info,  Node: Unit srfi-4 - blob->s8vector/shared,  Next: Unit srfi-4 - blob->u16vector/shared,  Prev: Unit srfi-4 - blob->u8vector/shared,  Up: Unit srfi-4

21.27 blob->s8vector/shared
===========================


File: chicken.info,  Node: Unit srfi-4 - blob->u16vector/shared,  Next: Unit srfi-4 - blob->s16vector/shared,  Prev: Unit srfi-4 - blob->s8vector/shared,  Up: Unit srfi-4

21.28 blob->u16vector/shared
============================


File: chicken.info,  Node: Unit srfi-4 - blob->s16vector/shared,  Next: Unit srfi-4 - blob->u32vector/shared,  Prev: Unit srfi-4 - blob->u16vector/shared,  Up: Unit srfi-4

21.29 blob->s16vector/shared
============================


File: chicken.info,  Node: Unit srfi-4 - blob->u32vector/shared,  Next: Unit srfi-4 - blob->s32vector/shared,  Prev: Unit srfi-4 - blob->s16vector/shared,  Up: Unit srfi-4

21.30 blob->u32vector/shared
============================


File: chicken.info,  Node: Unit srfi-4 - blob->s32vector/shared,  Next: Unit srfi-4 - blob->f32vector/shared,  Prev: Unit srfi-4 - blob->u32vector/shared,  Up: Unit srfi-4

21.31 blob->s32vector/shared
============================


File: chicken.info,  Node: Unit srfi-4 - blob->f32vector/shared,  Next: Unit srfi-4 - blob->f64vector/shared,  Prev: Unit srfi-4 - blob->s32vector/shared,  Up: Unit srfi-4

21.32 blob->f32vector/shared
============================


File: chicken.info,  Node: Unit srfi-4 - blob->f64vector/shared,  Next: Unit srfi-4 - subu8vector,  Prev: Unit srfi-4 - blob->f32vector/shared,  Up: Unit srfi-4

21.33 blob->f64vector/shared
============================


[procedure] (blob->u8vector BLOB)
[procedure] (blob->s8vector BLOB)
[procedure] (blob->u16vector BLOB)
[procedure] (blob->s16vector BLOB)
[procedure] (blob->u32vector BLOB)
[procedure] (blob->s32vector BLOB)
[procedure] (blob->f32vector BLOB)
[procedure] (blob->f64vector BLOB)
[procedure] (blob->u8vector/shared BLOB)
[procedure] (blob->s8vector/shared BLOB)
[procedure] (blob->u16vector/shared BLOB)
[procedure] (blob->s16vector/shared BLOB)
[procedure] (blob->u32vector/shared BLOB)
[procedure] (blob->s32vector/shared BLOB)
[procedure] (blob->f32vector/shared BLOB)
[procedure] (blob->f64vector/shared BLOB)
 Each of these procedures return a vector where the argument `BLOB' is
taken as a 'packed' representation of the contents of the vector. The
`/shared' variants return a vector that shares memory with the contents
of the blob.


File: chicken.info,  Node: Unit srfi-4 - subu8vector,  Next: Unit srfi-4 - subu16vector,  Prev: Unit srfi-4 - blob->f64vector/shared,  Up: Unit srfi-4

21.34 subu8vector
=================


File: chicken.info,  Node: Unit srfi-4 - subu16vector,  Next: Unit srfi-4 - subu32vector,  Prev: Unit srfi-4 - subu8vector,  Up: Unit srfi-4

21.35 subu16vector
==================


File: chicken.info,  Node: Unit srfi-4 - subu32vector,  Next: Unit srfi-4 - subs8vector,  Prev: Unit srfi-4 - subu16vector,  Up: Unit srfi-4

21.36 subu32vector
==================


File: chicken.info,  Node: Unit srfi-4 - subs8vector,  Next: Unit srfi-4 - subs16vector,  Prev: Unit srfi-4 - subu32vector,  Up: Unit srfi-4

21.37 subs8vector
=================


File: chicken.info,  Node: Unit srfi-4 - subs16vector,  Next: Unit srfi-4 - subs32vector,  Prev: Unit srfi-4 - subs8vector,  Up: Unit srfi-4

21.38 subs16vector
==================


File: chicken.info,  Node: Unit srfi-4 - subs32vector,  Next: Unit srfi-4 - subf32vector,  Prev: Unit srfi-4 - subs16vector,  Up: Unit srfi-4

21.39 subs32vector
==================


File: chicken.info,  Node: Unit srfi-4 - subf32vector,  Next: Unit srfi-4 - subf64vector,  Prev: Unit srfi-4 - subs32vector,  Up: Unit srfi-4

21.40 subf32vector
==================


File: chicken.info,  Node: Unit srfi-4 - subf64vector,  Next: Unit srfi-4 - read-u8vector,  Prev: Unit srfi-4 - subf32vector,  Up: Unit srfi-4

21.41 subf64vector
==================


[procedure] (subu8vector U8VECTOR FROM TO)
[procedure] (subu16vector U16VECTOR FROM TO)
[procedure] (subu32vector U32VECTOR FROM TO)
[procedure] (subs8vector S8VECTOR FROM TO)
[procedure] (subs16vector S16VECTOR FROM TO)
[procedure] (subs32vector S32VECTOR FROM TO)
[procedure] (subf32vector F32VECTOR FROM TO)
[procedure] (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.


File: chicken.info,  Node: Unit srfi-4 - read-u8vector,  Next: Unit srfi-4 - read-u8vector!,  Prev: Unit srfi-4 - subf64vector,  Up: Unit srfi-4

21.42 read-u8vector
===================


[procedure] (read-u8vector LENGTH [PORT])
 Reads `LENGTH' bytes from the `PORT' and returns a fresh `u8vector' or
less if end-of-file is encountered. `PORT' defaults to the value of
`(current-input-port)'. If `LENGTH' is `#f', the vector will be filled
completely until end-of-file is reached.


File: chicken.info,  Node: Unit srfi-4 - read-u8vector!,  Next: Unit srfi-4 - write-u8vector,  Prev: Unit srfi-4 - read-u8vector,  Up: Unit srfi-4

21.43 read-u8vector!
====================


[procedure] (read-u8vector! LENGTH U8VECTOR [PORT [START]])
 Reads `LENGTH' bytes from the `PORT' writing the read input into
`U8VECTOR' beginning at `START' (or 0 if not given). `PORT' defaults to
the value of `(current-input-port)'. If `LENGTH' is `#f', the vector
will be filled completely until end-of-file is reached. This procedure
returns the number of bytes read.


File: chicken.info,  Node: Unit srfi-4 - write-u8vector,  Prev: Unit srfi-4 - read-u8vector!,  Up: Unit srfi-4

21.44 write-u8vector
====================


[procedure] (write-u8vector U8VECTOR [PORT [START [END]]])
 Writes the bytes `U8VECTOR' between the indices `START' (inclusive)
and `END' (exclusive) to `PORT'. `PORT' defaults to the value of
`(current-output-port)'.

Previous: *Note Unit srfi-1: Unit srfi-1.

   Next: *Note Unit srfi-13: Unit srfi-13.


File: chicken.info,  Node: Unit srfi-13,  Next: Unit srfi-14,  Prev: Unit srfi-4,  Up: Top

22 Unit srfi-13
***************

String library, see the documentation for SRFI-13
(http://srfi.schemers.org/srfi-13/srfi-13.html)

   On systems that support dynamic loading, the `srfi-13' unit can be
made available in the interpreter (`csi') by entering

     (require-extension srfi-13)
   Previous: *Note Unit srfi-4: Unit srfi-4.

   Next: *Note Unit srfi-14: Unit srfi-14.


File: chicken.info,  Node: Unit srfi-14,  Next: Unit srfi-69,  Prev: Unit srfi-13,  Up: Top

23 Unit srfi-14
***************

Character set library, see the documentation for SRFI-14
(http://srfi.schemers.org/srfi-14/srfi-14.html)

   On systems that support dynamic loading, the `srfi-14' unit can be
made available in the interpreter (`csi') by entering

     (require-extension srfi-14)
   This library provides only the Latin-1 character set.

   Previous: *Note Unit srfi-13: Unit srfi-13.

   Next: *Note Unit srfi-69: Unit srfi-69.


File: chicken.info,  Node: Unit srfi-69,  Next: Unit match,  Prev: Unit srfi-14,  Up: Top

24 Unit srfi-69
***************

* Menu:

* Unit srfi-69 - Hash Table Procedures::
* Unit srfi-69 - Hashing Functions::

   CHICKEN implements SRFI 69 with SRFI 90 extensions. For more
information, see SRFI-69
(http://srfi.schemers.org/srfi-69/srfi-69.html) and SRFI-90
(http://srfi.schemers.org/srfi-90/srfi-90.html).


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures,  Next: Unit srfi-69 - Hashing Functions,  Up: Unit srfi-69

24.1 Hash Table Procedures
==========================

* Menu:

* Unit srfi-69 - Hash Table Procedures - make-hash-table::
* Unit srfi-69 - Hash Table Procedures - hash-table?::
* Unit srfi-69 - Hash Table Procedures - hash-table-size::
* Unit srfi-69 - Hash Table Procedures - hash-table-equivalence-function::
* Unit srfi-69 - Hash Table Procedures - hash-table-hash-function::
* Unit srfi-69 - Hash Table Procedures - hash-table-min-load::
* Unit srfi-69 - Hash Table Procedures - hash-table-max-load::
* Unit srfi-69 - Hash Table Procedures - hash-table-weak-keys::
* Unit srfi-69 - Hash Table Procedures - hash-table-weak-values::
* Unit srfi-69 - Hash Table Procedures - hash-table-has-initial?::
* Unit srfi-69 - Hash Table Procedures - hash-table-initial::
* Unit srfi-69 - Hash Table Procedures - hash-table-keys::
* Unit srfi-69 - Hash Table Procedures - hash-table-values::
* Unit srfi-69 - Hash Table Procedures - hash-table->alist::
* Unit srfi-69 - Hash Table Procedures - alist->hash-table::
* Unit srfi-69 - Hash Table Procedures - hash-table-ref::
* Unit srfi-69 - Hash Table Procedures - hash-table-ref/default::
* Unit srfi-69 - Hash Table Procedures - hash-table-exists?::
* Unit srfi-69 - Hash Table Procedures - hash-table-set!::
* Unit srfi-69 - Hash Table Procedures - hash-table-update!::
* Unit srfi-69 - Hash Table Procedures - hash-table-update!/default::
* Unit srfi-69 - Hash Table Procedures - hash-table-copy::
* Unit srfi-69 - Hash Table Procedures - hash-table-delete!::
* Unit srfi-69 - Hash Table Procedures - hash-table-remove!::
* Unit srfi-69 - Hash Table Procedures - hash-table-clear!::
* Unit srfi-69 - Hash Table Procedures - hash-table-merge::
* Unit srfi-69 - Hash Table Procedures - hash-table-merge!::
* Unit srfi-69 - Hash Table Procedures - hash-table-map::
* Unit srfi-69 - Hash Table Procedures - hash-table-fold::
* Unit srfi-69 - Hash Table Procedures - hash-table-for-each::
* Unit srfi-69 - Hash Table Procedures - hash-table-walk::


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - make-hash-table,  Next: Unit srfi-69 - Hash Table Procedures - hash-table?,  Up: Unit srfi-69 - Hash Table Procedures

24.1.1 make-hash-table
----------------------


[procedure] (make-hash-table [TEST HASH SIZE] #:TEST #:HASH #:SIZE #:INITIAL #:MIN-LOAD #:MAX-LOAD #:WEAK-KEYS #:WEAK-VALUES)
 Returns a new `HASH-TABLE' with the supplied configuration.

`TEST'
     The equivalence function.

`HASH'
     The hash function.

`SIZE'
     The expected number of table elements.

`INITIAL'
     The default initial value.

`MIN-LOAD'
     The minimum load factor. A `flonum' in (0.0 1.0).

`MAX-LOAD'
     The maximum load factor. A `flonum' in (0.0 1.0).

`WEAK-KEYS'
     Use weak references for keys. (Ignored)

`WEAK-VALUES'
     Use weak references for values. (Ignored)

(No, the keyword parameters are not uppercase.)


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table?,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-size,  Prev: Unit srfi-69 - Hash Table Procedures - make-hash-table,  Up: Unit srfi-69 - Hash Table Procedures

24.1.2 hash-table?
------------------


[procedure] (hash-table? OBJECT)
 Is the `OBJECT' a `hash-table'?


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-size,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-equivalence-function,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table?,  Up: Unit srfi-69 - Hash Table Procedures

24.1.3 hash-table-size
----------------------


[procedure] (hash-table-size HASH-TABLE)
 The `HASH-TABLE' size.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-equivalence-function,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-hash-function,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-size,  Up: Unit srfi-69 - Hash Table Procedures

24.1.4 hash-table-equivalence-function
--------------------------------------


[procedure] (hash-table-equivalence-function HASH-TABLE)
 The `HASH-TABLE' `equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-hash-function,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-min-load,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-equivalence-function,  Up: Unit srfi-69 - Hash Table Procedures

24.1.5 hash-table-hash-function
-------------------------------


[procedure] (hash-table-hash-function HASH-TABLE)
 The `HASH-TABLE' `hash-function'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-min-load,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-max-load,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-hash-function,  Up: Unit srfi-69 - Hash Table Procedures

24.1.6 hash-table-min-load
--------------------------


[procedure] (hash-table-min-load HASH-TABLE)
 The `HASH-TABLE' minimum load factor.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-max-load,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-weak-keys,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-min-load,  Up: Unit srfi-69 - Hash Table Procedures

24.1.7 hash-table-max-load
--------------------------


[procedure] (hash-table-max-load HASH-TABLE)
 The `HASH-TABLE' maximum load factor.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-weak-keys,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-weak-values,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-max-load,  Up: Unit srfi-69 - Hash Table Procedures

24.1.8 hash-table-weak-keys
---------------------------


[procedure] (hash-table-weak-keys HASH-TABLE)
 Does the `HASH-TABLE' weak references for keys?


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-weak-values,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-has-initial?,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-weak-keys,  Up: Unit srfi-69 - Hash Table Procedures

24.1.9 hash-table-weak-values
-----------------------------


[procedure] (hash-table-weak-values HASH-TABLE)
 Does the `HASH-TABLE' weak references for values?


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-has-initial?,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-initial,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-weak-values,  Up: Unit srfi-69 - Hash Table Procedures

24.1.10 hash-table-has-initial?
-------------------------------


[procedure] (hash-table-has-initial? HASH-TABLE)
 Does the `HASH-TABLE' have a default initial value?


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-initial,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-keys,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-has-initial?,  Up: Unit srfi-69 - Hash Table Procedures

24.1.11 hash-table-initial
--------------------------


[procedure] (hash-table-initial HASH-TABLE)
 The `HASH-TABLE' default initial value.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-keys,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-values,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-initial,  Up: Unit srfi-69 - Hash Table Procedures

24.1.12 hash-table-keys
-----------------------


[procedure] (hash-table-keys HASH-TABLE)
 Returns a list of the keys in the `HASH-TABLE' population.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-values,  Next: Unit srfi-69 - Hash Table Procedures - hash-table->alist,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-keys,  Up: Unit srfi-69 - Hash Table Procedures

24.1.13 hash-table-values
-------------------------


[procedure] (hash-table-values HASH-TABLE)
 Returns a list of the values in the `HASH-TABLE' population.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table->alist,  Next: Unit srfi-69 - Hash Table Procedures - alist->hash-table,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-values,  Up: Unit srfi-69 - Hash Table Procedures

24.1.14 hash-table->alist
-------------------------


[procedure] (hash-table->alist HASH-TABLE)
 Returns the population of the `HASH-TABLE' as an `association-list'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - alist->hash-table,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-ref,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table->alist,  Up: Unit srfi-69 - Hash Table Procedures

24.1.15 alist->hash-table
-------------------------


[procedure] (alist->hash-table ASSOCIATION-LIST [MAKE-HASH-TABLE-PARAMETER ...])
 Returns a new `HASH-TABLE', configured using the optional
`MAKE-HASH-TABLE-PARAMETER ...'. The `HASH-TABLE' is populated from the
`ASSOCIATION-LIST'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-ref,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-ref/default,  Prev: Unit srfi-69 - Hash Table Procedures - alist->hash-table,  Up: Unit srfi-69 - Hash Table Procedures

24.1.16 hash-table-ref
----------------------


[procedure] (hash-table-ref HASH-TABLE KEY)
 Returns the `VALUE' for the `KEY' in the `HASH-TABLE'.

Aborts with an exception when the `KEY' is missing.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-ref/default,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-exists?,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-ref,  Up: Unit srfi-69 - Hash Table Procedures

24.1.17 hash-table-ref/default
------------------------------


[procedure] (hash-table-ref/default HASH-TABLE KEY DEFAULT)
 Returns the `VALUE' for the `KEY' in the `HASH-TABLE', or the
`DEFAULT' when the `KEY' is missing.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-exists?,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-set!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-ref/default,  Up: Unit srfi-69 - Hash Table Procedures

24.1.18 hash-table-exists?
--------------------------


[procedure] (hash-table-exists? HASH-TABLE KEY)
 Does the `KEY' exist in the `HASH-TABLE'?


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-set!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-update!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-exists?,  Up: Unit srfi-69 - Hash Table Procedures

24.1.19 hash-table-set!
-----------------------


[procedure] (hash-table-set! HASH-TABLE KEY VALUE)
 Set the `VALUE' for the `KEY' in the `HASH-TABLE'.

A setter for `hash-table-ref' is defined, so

     (*set!* (hash-table-ref HASH-TABLE KEY) VALUE)
   is equivalent to

     (hash-table-set! HASH-TABLE KEY VALUE)


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-update!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-update!/default,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-set!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.20 hash-table-update!
--------------------------


[procedure] (hash-table-update! HASH-TABLE KEY [UPDATE-FUNCTION [DEFAULT-VALUE-FUNCTION]])
 Sets or replaces the `VALUE' for `KEY' in the `HASH-TABLE'.

The `UPDATE-FUNCTION' takes the existing `VALUE' for `KEY' and returns
the new `VALUE'. The default is `identity'

   The `DEFAULT-VALUE-FUNCTION' is called when the entry for `KEY' is
missing. The default uses the `(hash-table-initial-value)', if
provided. Otherwise aborts with an exception.

   Returns the new `VALUE'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-update!/default,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-copy,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-update!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.21 hash-table-update!/default
----------------------------------


[procedure] (hash-table-update! HASH-TABLE KEY UPDATE-FUNCTION DEFAULT-VALUE)
 Sets or replaces the `VALUE' for `KEY' in the `HASH-TABLE'.

The `UPDATE-FUNCTION' takes the existing `VALUE' for `KEY' and returns
the new `VALUE'.

   The `DEFAULT-VALUE' is used when the entry for `KEY' is missing.

   Returns the new `VALUE'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-copy,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-delete!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-update!/default,  Up: Unit srfi-69 - Hash Table Procedures

24.1.22 hash-table-copy
-----------------------


[procededure] (hash-table-copy HASH-TABLE)
 Returns a shallow copy of the `HASH-TABLE'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-delete!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-remove!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-copy,  Up: Unit srfi-69 - Hash Table Procedures

24.1.23 hash-table-delete!
--------------------------


[procedure] (hash-table-delete! HASH-TABLE KEY)
 Deletes the entry for `KEY' in the `HASH-TABLE'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-remove!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-clear!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-delete!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.24 hash-table-remove!
--------------------------


[procedure] (hash-table-remove! HASH-TABLE PROC)
 Calls `PROC' for all entries in `HASH-TABLE' with the key and value of
each entry. If `PROC' returns true, then that entry is removed.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-clear!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-merge,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-remove!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.25 hash-table-clear!
-------------------------


[procedure] (hash-table-clear! HASH-TABLE)
 Deletes all entries in `HASH-TABLE'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-merge,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-merge!,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-clear!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.26 hash-table-merge
------------------------


[procedure] (hash-table-merge HASH-TABLE-1 HASH-TABLE-2)
 Returns a new `HASH-TABLE' with the union of `HASH-TABLE-1' and
`HASH-TABLE-2'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-merge!,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-map,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-merge,  Up: Unit srfi-69 - Hash Table Procedures

24.1.27 hash-table-merge!
-------------------------


[procedure] (hash-table-merge! HASH-TABLE-1 HASH-TABLE-2)
 Returns `HASH-TABLE-1' as the union of `HASH-TABLE-1' and
`HASH-TABLE-2'.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-map,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-fold,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-merge!,  Up: Unit srfi-69 - Hash Table Procedures

24.1.28 hash-table-map
----------------------


[procedure] (hash-table-map HASH-TABLE FUNC)
 Calls `FUNC' for all entries in `HASH-TABLE' with the key and value of
each entry.

Returns a list of the results of each call.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-fold,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-for-each,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-map,  Up: Unit srfi-69 - Hash Table Procedures

24.1.29 hash-table-fold
-----------------------


[procedure] (hash-table-fold HASH-TABLE FUNC INIT)
 Calls `FUNC' for all entries in `HASH-TABLE' with the key and value of
each entry, and the current folded value. The initial folded value is
`INIT'.

Returns the final folded value.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-for-each,  Next: Unit srfi-69 - Hash Table Procedures - hash-table-walk,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-fold,  Up: Unit srfi-69 - Hash Table Procedures

24.1.30 hash-table-for-each
---------------------------


[procedure] (hash-table-for-each HASH-TABLE PROC)
 Calls `PROC' for all entries in `HASH-TABLE' with the key and value of
each entry.


File: chicken.info,  Node: Unit srfi-69 - Hash Table Procedures - hash-table-walk,  Prev: Unit srfi-69 - Hash Table Procedures - hash-table-for-each,  Up: Unit srfi-69 - Hash Table Procedures

24.1.31 hash-table-walk
-----------------------


[procedure] (hash-table-walk HASH-TABLE PROC)
 Calls `PROC' for all entries in `HASH-TABLE' with the key and value of
each entry.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions,  Prev: Unit srfi-69 - Hash Table Procedures,  Up: Unit srfi-69

24.2 Hashing Functions
======================

* Menu:

* Unit srfi-69 - Hashing Functions - number-hash::
* Unit srfi-69 - Hashing Functions - object-uid-hash::
* Unit srfi-69 - Hashing Functions - symbol-hash::
* Unit srfi-69 - Hashing Functions - keyword-hash::
* Unit srfi-69 - Hashing Functions - string-hash::
* Unit srfi-69 - Hashing Functions - string-ci-hash::
* Unit srfi-69 - Hashing Functions - eq?-hash::
* Unit srfi-69 - Hashing Functions - eqv?-hash::
* Unit srfi-69 - Hashing Functions - equal?-hash::
* Unit srfi-69 - Hashing Functions - hash::
* Unit srfi-69 - Hashing Functions - hash-by-identity::

   All hash functions return a `fixnum' in the range [0 `BOUND').


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - number-hash,  Next: Unit srfi-69 - Hashing Functions - object-uid-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.1 number-hash
------------------


[procedure] (number-hash NUMBER [BOUND])
 For use with `=' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - object-uid-hash,  Next: Unit srfi-69 - Hashing Functions - symbol-hash,  Prev: Unit srfi-69 - Hashing Functions - number-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.2 object-uid-hash
----------------------


[procedure] (object-uid-hash OBJECT [BOUND])
 Currently a synonym for `equal?-hash'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - symbol-hash,  Next: Unit srfi-69 - Hashing Functions - keyword-hash,  Prev: Unit srfi-69 - Hashing Functions - object-uid-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.3 symbol-hash
------------------


[procedure] (symbol-hash SYMBOL [BOUND])
 For use with `eq?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - keyword-hash,  Next: Unit srfi-69 - Hashing Functions - string-hash,  Prev: Unit srfi-69 - Hashing Functions - symbol-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.4 keyword-hash
-------------------


[procedure] (keyword-hash KEYWORD [BOUND])
 For use with `eq?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - string-hash,  Next: Unit srfi-69 - Hashing Functions - string-ci-hash,  Prev: Unit srfi-69 - Hashing Functions - keyword-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.5 string-hash
------------------


[procedure] (string-hash STRING [BOUND])
 For use with `string=?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - string-ci-hash,  Next: Unit srfi-69 - Hashing Functions - eq?-hash,  Prev: Unit srfi-69 - Hashing Functions - string-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.6 string-ci-hash
---------------------


[procedure] (string-ci-hash STRING [BOUND])
 For use with `string-ci=?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - eq?-hash,  Next: Unit srfi-69 - Hashing Functions - eqv?-hash,  Prev: Unit srfi-69 - Hashing Functions - string-ci-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.7 eq?-hash
---------------


[procedure] (eq?-hash OBJECT [BOUND])
 For use with `eq?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - eqv?-hash,  Next: Unit srfi-69 - Hashing Functions - equal?-hash,  Prev: Unit srfi-69 - Hashing Functions - eq?-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.8 eqv?-hash
----------------


[procedure] (eqv?-hash OBJECT [BOUND])
 For use with `eqv?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - equal?-hash,  Next: Unit srfi-69 - Hashing Functions - hash,  Prev: Unit srfi-69 - Hashing Functions - eqv?-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.9 equal?-hash
------------------


[procedure] (equal?-hash OBJECT [BOUND])
 For use with `equal?' as a `hash-table-equivalence-function'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - hash,  Next: Unit srfi-69 - Hashing Functions - hash-by-identity,  Prev: Unit srfi-69 - Hashing Functions - equal?-hash,  Up: Unit srfi-69 - Hashing Functions

24.2.10 hash
------------


[procedure] (hash OBJECT [BOUND])
 Synonym for `equal?-hash'.


File: chicken.info,  Node: Unit srfi-69 - Hashing Functions - hash-by-identity,  Prev: Unit srfi-69 - Hashing Functions - hash,  Up: Unit srfi-69 - Hashing Functions

24.2.11 hash-by-identity
------------------------


[procedure] (hash-by-identity OBJECT [BOUND])
 Synonym for `eq?-hash'.

Previous: *Note Unit srfi-14: Unit srfi-14. Next: *Note Unit match:
Unit match.


File: chicken.info,  Node: Unit match,  Next: Unit regex,  Prev: Unit srfi-69,  Up: Top

25 Unit match
*************

The runtime-support code for the Pattern Matching
(http://chicken.wiki.br/Pattern%20matching) extensions. Note that to
use the macros in normal compiled code it is not required to declare
this unit as used. It is only necessary to do so if forms containing
these macros are to be expanded at runtime.

   Previous: *Note Unit srfi-14: Unit srfi-14.

   Next: *Note Unit regex: Unit regex.


File: chicken.info,  Node: Unit regex,  Next: Unit srfi-18,  Prev: Unit match,  Up: Top

26 Unit regex
*************

* Menu:

* Unit regex - grep::
* Unit regex - glob->regexp::
* Unit regex - glob?::
* Unit regex - regexp::
* Unit regex - regexp*::
* Unit regex - regexp?::
* Unit regex - regexp-optimize::
* Unit regex - string-match::
* Unit regex - string-match-positions::
* Unit regex - string-search::
* Unit regex - string-search-positions::
* Unit regex - string-split-fields::
* Unit regex - string-substitute::
* Unit regex - string-substitute*::
* Unit regex - regexp-escape::
* Unit regex - make-anchored-pattern::

   This library unit provides support for regular expressions. The
regular  expression package used is `PCRE' (_Perl Compatible Regular
Expressions_)  written by Philip Hazel. See http://www.pcre.org
(http://www.pcre.org) for information about the particular regexp
flavor and extensions provided by this library.

   To test that PCRE support has been built into Chicken properly, try:

     (require 'regex)
     (feature? 'pcre) *=>* #t


File: chicken.info,  Node: Unit regex - grep,  Next: Unit regex - glob->regexp,  Up: Unit regex

26.1 grep
=========


[procedure] (grep REGEX LIST)
 Returns all items of `LIST' that match the regular expression `REGEX'.
This procedure could be defined as follows:

     (*define* (*grep* regex lst)
       (filter (*lambda* (x) (string-search regex x)) lst) )


File: chicken.info,  Node: Unit regex - glob->regexp,  Next: Unit regex - glob?,  Prev: Unit regex - grep,  Up: Unit regex

26.2 glob->regexp
=================


[procedure] (glob->regexp PATTERN)
 Converts the file-pattern `PATTERN' into a regular expression.

     (glob->regexp *"foo.*"*)
     *=>* *"foo\..*"*
`PATTERN' should follow "glob" syntax. Allowed wildcards are


*
[C...]
[C1-C2]
[-C...]
?


File: chicken.info,  Node: Unit regex - glob?,  Next: Unit regex - regexp,  Prev: Unit regex - glob->regexp,  Up: Unit regex

26.3 glob?
==========


[procedure] (glob? STRING)
 Does the `STRING' have any "glob" wildcards?

A string without any "glob" wildcards does not meet the criteria, even
though it technically is a valid "glob" file-pattern.


File: chicken.info,  Node: Unit regex - regexp,  Next: Unit regex - regexp*,  Prev: Unit regex - glob?,  Up: Unit regex

26.4 regexp
===========


[procedure] (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.


File: chicken.info,  Node: Unit regex - regexp*,  Next: Unit regex - regexp?,  Prev: Unit regex - regexp,  Up: Unit regex

26.5 regexp*
============


[procedure] (regexp* STRING [OPTIONS [TABLES]])
 Returns a precompiled regular expression object for `string'. The
optional argument `OPTIONS' must be a list of option symbols. The
optional argument `TABLES' must be a character definitions table (not
defined here).

Option Symbols:

caseless
     Character case insensitive match

multiline
     Equivalent to Perl's /m option

dotall
     Equivalent to Perl's /s option

extended
     Ignore whitespace

anchored
     Anchor pattern match

dollar-endonly
     `$' metacharacter in the pattern matches only at the end of the
     subject string

extra
     Currently of very little use

notbol
     First character of the string is not the beginning of a line

noteol
     End of the string is not the end of a line

ungreedy
     Inverts the "greediness" of the quantifiers so that they are not
     greedy by default

notempty
     The empty string is not considered to be a valid match

utf8
     UTF-8 encoded characters

no-auto-capture
     Disables the use of numbered capturing parentheses

no-utf8-check
     Skip valid UTF-8 sequence check

auto-callout
     Automatically inserts callout items (not defined here)

partial
     Partial match ok

firstline
     An unanchored pattern is required to match before or at the first
     newline

dupnames
     Names used to identify capturing subpatterns need not be unique

newline-cr
     Newline definition is `\r'

newline-lf
     Newline definition is `\n'

newline-crlf
     Newline definition is `\r\n'

newline-anycrlf
     Newline definition is any of `\r', `\n', or `\r\n'

newline-any
     Newline definition is any Unicode newline sequence

bsr-anycrlf
     `\R' escape sequence matches only CR, LF, or CRLF

bsr-unicode
     `\R' escape sequence matches only Unicode newline sequence

dfa-shortest
     Currently unused

dfa-restart
     Currently unused



File: chicken.info,  Node: Unit regex - regexp?,  Next: Unit regex - regexp-optimize,  Prev: Unit regex - regexp*,  Up: Unit regex

26.6 regexp?
============


[procedure] (regexp? X)
 Returns `#t' if `X' is a precompiled regular expression, or `#f'
otherwise.


File: chicken.info,  Node: Unit regex - regexp-optimize,  Next: Unit regex - string-match,  Prev: Unit regex - regexp?,  Up: Unit regex

26.7 regexp-optimize
====================


[procedure] (regexp-optimize RX)

 Perform available optimizations for the precompiled regular expression
`RX'. Returns `#t' when optimization performed, and `#f' otherwise.


File: chicken.info,  Node: Unit regex - string-match,  Next: Unit regex - string-match-positions,  Prev: Unit regex - regexp-optimize,  Up: Unit regex

26.8 string-match
=================


File: chicken.info,  Node: Unit regex - string-match-positions,  Next: Unit regex - string-search,  Prev: Unit regex - string-match,  Up: Unit regex

26.9 string-match-positions
===========================


[procedure] (string-match REGEXP STRING [START])
[procedure] (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 `^ ... $'. If invoked with a precompiled
regular expression argument (by using `regexp'), `string-match' is
identical to `string-search'.


File: chicken.info,  Node: Unit regex - string-search,  Next: Unit regex - string-search-positions,  Prev: Unit regex - string-match-positions,  Up: Unit regex

26.10 string-search
===================


File: chicken.info,  Node: Unit regex - string-search-positions,  Next: Unit regex - string-split-fields,  Prev: Unit regex - string-search,  Up: Unit regex

26.11 string-search-positions
=============================


[procedure] (string-search REGEXP STRING [START [RANGE]])
[procedure] (string-search-positions REGEXP STRING [START [RANGE]])
 Searches for the first match of the regular expression in `REGEXP'
with `STRING'. The search can be limited to `RANGE' characters.


File: chicken.info,  Node: Unit regex - string-split-fields,  Next: Unit regex - string-substitute,  Prev: Unit regex - string-search-positions,  Up: Unit regex

26.12 string-split-fields
=========================


[procedure] (string-split-fields REGEXP STRING [MODE [START]])
 Splits `STRING' into a list of fields according to `MODE', where
`MODE' can be the keyword `#:infix' (`REGEXP' matches field separator),
the keyword `#:suffix' (`REGEXP' matches field terminator) or `#t'
(`REGEXP' matches field), which is the default.

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


File: chicken.info,  Node: Unit regex - string-substitute,  Next: Unit regex - string-substitute*,  Prev: Unit regex - string-split-fields,  Up: Unit regex

26.13 string-substitute
=======================


[procedure] (string-substitute REGEXP SUBST STRING [MODE])
 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
`MODE' 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)"*
Note that a regular expression that matches an empty string will signal
an error.


File: chicken.info,  Node: Unit regex - string-substitute*,  Next: Unit regex - regexp-escape,  Prev: Unit regex - string-substitute,  Up: Unit regex

26.14 string-substitute*
========================


[procedure] (string-substitute* STRING SMAP [MODE])
 Substitutes elements of `STRING' with `string-substitute' 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!"*


File: chicken.info,  Node: Unit regex - regexp-escape,  Next: Unit regex - make-anchored-pattern,  Prev: Unit regex - string-substitute*,  Up: Unit regex

26.15 regexp-escape
===================


[procedure] (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.\\*\\$"*


File: chicken.info,  Node: Unit regex - make-anchored-pattern,  Prev: Unit regex - regexp-escape,  Up: Unit regex

26.16 make-anchored-pattern
===========================


[procedure] (make-anchored-pattern REGEXP [WITHOUT-BOL [WITHOUT-EOL]])
 Makes an anchored pattern from `REGEXP' (a string or a precompiled
regular expression) and returns the updated pattern. When `WITHOUT-BOL'
is `#t' the beginning-of-line anchor is not added. When `WITHOUT-EOL'
is `#t' the end-of-line anchor is not added.

The `WITHOUT-BOL' and {WITHOUT-EOL}} arguments are ignored for a
precompiled regular expression.

   Previous: *Note Unit match: Unit match.

   Next: *Note Unit srfi-18: Unit srfi-18.


File: chicken.info,  Node: Unit srfi-18,  Next: Unit posix,  Prev: Unit regex,  Up: Top

27 Unit srfi-18
***************

* Menu:

* Unit srfi-18 - thread-signal!::
* Unit srfi-18 - thread-quantum::
* Unit srfi-18 - thread-quantum-set!::
* Unit srfi-18 - thread-suspend!::
* Unit srfi-18 - thread-resume!::
* Unit srfi-18 - thread-wait-for-i/o!::
* Unit srfi-18 - time->milliseconds::
* Unit srfi-18 - milliseconds->time::

   A simple multithreading package. This threading package follows
largely the specification of SRFI-18. For more information see the
documentation for SRFI-18
(http://srfi.schemers.org/srfi-18/srfi-18.html).

   Notes:

   * `thread-start!' accepts a thunk (a zero argument procedure) as
     argument, which is equivalent to `(thread-start! (make-thread
     THUNK))'.

   * `thread-sleep!' accepts a seconds real number value in addition to
     a time object.

   * When an uncaught exception (i.e. an error) is signalled in a
     thread other than the primordial thread and warnings are enabled
     (see: `enable-warnings', then a warning message is written to the
     port that is the value of `(current-error-port)'.

   * Blocking I/O will block all threads, except for some socket
     operations (see the section about the `tcp' unit). An exception is
     the read-eval-print loop on UNIX platforms: waiting for input will
     not block other threads, provided the current input port reads
     input from a console.

   * It is generally not a good idea for one thread to call a
     continuation created by another thread, if `dynamic-wind' is
     involved.

   * When more than one thread compete for the current time-slice, the
     thread that was waiting first will become the next runnable thread.

   * The dynamic environment of a thread consists of the following
     state:
        * The current input-, output- and error-port

        * The current exception handler

        * The values of all current parameters (created by
          `make-parameter')

        * Any pending `dynamic-wind' thunks.


   The following procedures are provided, in addition to the procedures
defined in SRFI-18:


File: chicken.info,  Node: Unit srfi-18 - thread-signal!,  Next: Unit srfi-18 - thread-quantum,  Up: Unit srfi-18

27.1 thread-signal!
===================


[procedure] (thread-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.


File: chicken.info,  Node: Unit srfi-18 - thread-quantum,  Next: Unit srfi-18 - thread-quantum-set!,  Prev: Unit srfi-18 - thread-signal!,  Up: Unit srfi-18

27.2 thread-quantum
===================


[procedure] (thread-quantum THREAD)
 Returns the quantum of `THREAD', which is an exact integer specifying
the approximate time-slice of the thread in milliseconds.


File: chicken.info,  Node: Unit srfi-18 - thread-quantum-set!,  Next: Unit srfi-18 - thread-suspend!,  Prev: Unit srfi-18 - thread-quantum,  Up: Unit srfi-18

27.3 thread-quantum-set!
========================


[procedure] (thread-quantum-set! THREAD QUANTUM)
 Sets the quantum of `THREAD' to `QUANTUM'.


File: chicken.info,  Node: Unit srfi-18 - thread-suspend!,  Next: Unit srfi-18 - thread-resume!,  Prev: Unit srfi-18 - thread-quantum-set!,  Up: Unit srfi-18

27.4 thread-suspend!
====================


[procedure] (thread-suspend! THREAD)
 Suspends the execution of `THREAD' until resumed.


File: chicken.info,  Node: Unit srfi-18 - thread-resume!,  Next: Unit srfi-18 - thread-wait-for-i/o!,  Prev: Unit srfi-18 - thread-suspend!,  Up: Unit srfi-18

27.5 thread-resume!
===================


[procedure] (thread-resume! THREAD)
 Readies the suspended thread `THREAD'.


File: chicken.info,  Node: Unit srfi-18 - thread-wait-for-i/o!,  Next: Unit srfi-18 - time->milliseconds,  Prev: Unit srfi-18 - thread-resume!,  Up: Unit srfi-18

27.6 thread-wait-for-i/o!
=========================


[procedure] (thread-wait-for-i/o! FD [MODE])
 Suspends the current thread until input (`MODE' is `#:input'), output
(`MODE' is `#:output') or both (`MODE' is `#:all') is available. `FD'
should be a file-descriptor (not a port!) open for input or output,
respectively.


File: chicken.info,  Node: Unit srfi-18 - time->milliseconds,  Next: Unit srfi-18 - milliseconds->time,  Prev: Unit srfi-18 - thread-wait-for-i/o!,  Up: Unit srfi-18

27.7 time->milliseconds
=======================


[procedure] (time->milliseconds TIME)
 Converts a time object (as created via `current-time') into an exact
integer representing the number of milliseconds since process startup.


File: chicken.info,  Node: Unit srfi-18 - milliseconds->time,  Prev: Unit srfi-18 - time->milliseconds,  Up: Unit srfi-18

27.8 milliseconds->time
=======================


[procedure] (milliseconds->time ms)
 Converts into a time object an exact integer representing the number
of milliseconds since process startup.

This procedure may be useful in combination with `thread-sleep!' when
your compilation unit is using `(declare fixnum-arithmetic)'.  In that
case you won't be able to pass an inexact value to `thread-sleep!', but
you can do the following:


(define (thread-sleep!/ms ms)
  (thread-sleep!
   (milliseconds->time (+ ms (current-milliseconds)))))
 Previous: *Note Unit regex: Unit regex.

   Next: *Note Unit posix: Unit posix.


File: chicken.info,  Node: Unit posix,  Next: Unit utils,  Prev: Unit srfi-18,  Up: Top

28 Unit posix
*************

* Menu:

* Unit posix - Constants::
* Unit posix - Directories::
* Unit posix - Pipes::
* Unit posix - Fifos::
* Unit posix - File descriptors and low-level I/O::
* Unit posix - Retrieving file attributes::
* Unit posix - Changing file attributes::
* Unit posix - Processes::
* Unit posix - Hard and symbolic links::
* Unit posix - Retrieving user & group information::
* Unit posix - Changing user & group information::
* Unit posix - Record locking::
* Unit posix - Signal handling::
* Unit posix - Environment access::
* Unit posix - Memory mapped I/O::
* Unit posix - Date and time routines::
* Unit posix - Raw exit::
* Unit posix - ERRNO values::
* Unit posix - Finding files::
* Unit posix - Getting the hostname and system information::
* Unit posix - Setting the file buffering mode::
* Unit posix - Terminal ports::
* Unit posix - How Scheme procedures relate to UNIX C functions::
* Unit posix - Windows specific notes::

   This unit provides services as used on many UNIX-like systems.  Note
that the following definitions are not all available on non-UNIX
systems like Windows. See below for Windows specific notes.

   This unit uses the `regex', `scheduler', `extras' and `utils' units.

   All errors related to failing file-operations will signal a
condition of kind `(exn i/o file)'.


File: chicken.info,  Node: Unit posix - Constants,  Next: Unit posix - Directories,  Up: Unit posix

28.1 Constants
==============

* Menu:

* Unit posix - Constants - File-control Commands::
* Unit posix - Constants - Standard I/O file-descriptors::
* Unit posix - Constants - Open flags::
* Unit posix - Constants - Permission bits::


File: chicken.info,  Node: Unit posix - Constants - File-control Commands,  Next: Unit posix - Constants - Standard I/O file-descriptors,  Up: Unit posix - Constants

28.1.1 File-control Commands
----------------------------

* Menu:

* Unit posix - Constants - File-control Commands - fcntl/dupfd::
* Unit posix - Constants - File-control Commands - fcntl/getfd::
* Unit posix - Constants - File-control Commands - fcntl/setfd::
* Unit posix - Constants - File-control Commands - fcntl/getfl::
* Unit posix - Constants - File-control Commands - fcntl/setfl::


File: chicken.info,  Node: Unit posix - Constants - File-control Commands - fcntl/dupfd,  Next: Unit posix - Constants - File-control Commands - fcntl/getfd,  Up: Unit posix - Constants - File-control Commands

28.1.1.1 fcntl/dupfd
....................


File: chicken.info,  Node: Unit posix - Constants - File-control Commands - fcntl/getfd,  Next: Unit posix - Constants - File-control Commands - fcntl/setfd,  Prev: Unit posix - Constants - File-control Commands - fcntl/dupfd,  Up: Unit posix - Constants - File-control Commands

28.1.1.2 fcntl/getfd
....................


File: chicken.info,  Node: Unit posix - Constants - File-control Commands - fcntl/setfd,  Next: Unit posix - Constants - File-control Commands - fcntl/getfl,  Prev: Unit posix - Constants - File-control Commands - fcntl/getfd,  Up: Unit posix - Constants - File-control Commands

28.1.1.3 fcntl/setfd
....................


File: chicken.info,  Node: Unit posix - Constants - File-control Commands - fcntl/getfl,  Next: Unit posix - Constants - File-control Commands - fcntl/setfl,  Prev: Unit posix - Constants - File-control Commands - fcntl/setfd,  Up: Unit posix - Constants - File-control Commands

28.1.1.4 fcntl/getfl
....................


File: chicken.info,  Node: Unit posix - Constants - File-control Commands - fcntl/setfl,  Prev: Unit posix - Constants - File-control Commands - fcntl/getfl,  Up: Unit posix - Constants - File-control Commands

28.1.1.5 fcntl/setfl
....................


File: chicken.info,  Node: Unit posix - Constants - Standard I/O file-descriptors,  Next: Unit posix - Constants - Open flags,  Prev: Unit posix - Constants - File-control Commands,  Up: Unit posix - Constants

28.1.2 Standard I/O file-descriptors
------------------------------------

* Menu:

* Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin::
* Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout::
* Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr::


File: chicken.info,  Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin,  Next: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout,  Up: Unit posix - Constants - Standard I/O file-descriptors

28.1.2.1 fileno/stdin
.....................


File: chicken.info,  Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout,  Next: Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr,  Prev: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin,  Up: Unit posix - Constants - Standard I/O file-descriptors

28.1.2.2 fileno/stdout
......................


File: chicken.info,  Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr,  Prev: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout,  Up: Unit posix - Constants - Standard I/O file-descriptors

28.1.2.3 fileno/stderr
......................


File: chicken.info,  Node: Unit posix - Constants - Open flags,  Next: Unit posix - Constants - Permission bits,  Prev: Unit posix - Constants - Standard I/O file-descriptors,  Up: Unit posix - Constants

28.1.3 Open flags
-----------------

* Menu:

* Unit posix - Constants - Open flags - open/rdonly::
* Unit posix - Constants - Open flags - open/wronly::
* Unit posix - Constants - Open flags - open/rdwr::
* Unit posix - Constants - Open flags - open/read::
* Unit posix - Constants - Open flags - open/write::
* Unit posix - Constants - Open flags - open/creat::
* Unit posix - Constants - Open flags - open/append::
* Unit posix - Constants - Open flags - open/excl::
* Unit posix - Constants - Open flags - open/noctty::
* Unit posix - Constants - Open flags - open/nonblock::
* Unit posix - Constants - Open flags - open/trunc::
* Unit posix - Constants - Open flags - open/sync::
* Unit posix - Constants - Open flags - open/fsync::
* Unit posix - Constants - Open flags - open/binary::
* Unit posix - Constants - Open flags - open/text::


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/rdonly,  Next: Unit posix - Constants - Open flags - open/wronly,  Up: Unit posix - Constants - Open flags

28.1.3.1 open/rdonly
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/wronly,  Next: Unit posix - Constants - Open flags - open/rdwr,  Prev: Unit posix - Constants - Open flags - open/rdonly,  Up: Unit posix - Constants - Open flags

28.1.3.2 open/wronly
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/rdwr,  Next: Unit posix - Constants - Open flags - open/read,  Prev: Unit posix - Constants - Open flags - open/wronly,  Up: Unit posix - Constants - Open flags

28.1.3.3 open/rdwr
..................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/read,  Next: Unit posix - Constants - Open flags - open/write,  Prev: Unit posix - Constants - Open flags - open/rdwr,  Up: Unit posix - Constants - Open flags

28.1.3.4 open/read
..................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/write,  Next: Unit posix - Constants - Open flags - open/creat,  Prev: Unit posix - Constants - Open flags - open/read,  Up: Unit posix - Constants - Open flags

28.1.3.5 open/write
...................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/creat,  Next: Unit posix - Constants - Open flags - open/append,  Prev: Unit posix - Constants - Open flags - open/write,  Up: Unit posix - Constants - Open flags

28.1.3.6 open/creat
...................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/append,  Next: Unit posix - Constants - Open flags - open/excl,  Prev: Unit posix - Constants - Open flags - open/creat,  Up: Unit posix - Constants - Open flags

28.1.3.7 open/append
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/excl,  Next: Unit posix - Constants - Open flags - open/noctty,  Prev: Unit posix - Constants - Open flags - open/append,  Up: Unit posix - Constants - Open flags

28.1.3.8 open/excl
..................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/noctty,  Next: Unit posix - Constants - Open flags - open/nonblock,  Prev: Unit posix - Constants - Open flags - open/excl,  Up: Unit posix - Constants - Open flags

28.1.3.9 open/noctty
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/nonblock,  Next: Unit posix - Constants - Open flags - open/trunc,  Prev: Unit posix - Constants - Open flags - open/noctty,  Up: Unit posix - Constants - Open flags

28.1.3.10 open/nonblock
.......................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/trunc,  Next: Unit posix - Constants - Open flags - open/sync,  Prev: Unit posix - Constants - Open flags - open/nonblock,  Up: Unit posix - Constants - Open flags

28.1.3.11 open/trunc
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/sync,  Next: Unit posix - Constants - Open flags - open/fsync,  Prev: Unit posix - Constants - Open flags - open/trunc,  Up: Unit posix - Constants - Open flags

28.1.3.12 open/sync
...................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/fsync,  Next: Unit posix - Constants - Open flags - open/binary,  Prev: Unit posix - Constants - Open flags - open/sync,  Up: Unit posix - Constants - Open flags

28.1.3.13 open/fsync
....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/binary,  Next: Unit posix - Constants - Open flags - open/text,  Prev: Unit posix - Constants - Open flags - open/fsync,  Up: Unit posix - Constants - Open flags

28.1.3.14 open/binary
.....................


File: chicken.info,  Node: Unit posix - Constants - Open flags - open/text,  Prev: Unit posix - Constants - Open flags - open/binary,  Up: Unit posix - Constants - Open flags

28.1.3.15 open/text
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits,  Prev: Unit posix - Constants - Open flags,  Up: Unit posix - Constants

28.1.4 Permission bits
----------------------

* Menu:

* Unit posix - Constants - Permission bits - perm/irusr::
* Unit posix - Constants - Permission bits - perm/iwusr::
* Unit posix - Constants - Permission bits - perm/ixusr::
* Unit posix - Constants - Permission bits - perm/irgrp::
* Unit posix - Constants - Permission bits - perm/iwgrp::
* Unit posix - Constants - Permission bits - perm/ixgrp::
* Unit posix - Constants - Permission bits - perm/iroth::
* Unit posix - Constants - Permission bits - perm/iwoth::
* Unit posix - Constants - Permission bits - perm/ixoth::
* Unit posix - Constants - Permission bits - perm/irwxu::
* Unit posix - Constants - Permission bits - perm/irwxg::
* Unit posix - Constants - Permission bits - perm/irwxo::
* Unit posix - Constants - Permission bits - perm/isvtx::
* Unit posix - Constants - Permission bits - perm/isuid::
* Unit posix - Constants - Permission bits - perm/isgid::


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/irusr,  Next: Unit posix - Constants - Permission bits - perm/iwusr,  Up: Unit posix - Constants - Permission bits

28.1.4.1 perm/irusr
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/iwusr,  Next: Unit posix - Constants - Permission bits - perm/ixusr,  Prev: Unit posix - Constants - Permission bits - perm/irusr,  Up: Unit posix - Constants - Permission bits

28.1.4.2 perm/iwusr
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/ixusr,  Next: Unit posix - Constants - Permission bits - perm/irgrp,  Prev: Unit posix - Constants - Permission bits - perm/iwusr,  Up: Unit posix - Constants - Permission bits

28.1.4.3 perm/ixusr
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/irgrp,  Next: Unit posix - Constants - Permission bits - perm/iwgrp,  Prev: Unit posix - Constants - Permission bits - perm/ixusr,  Up: Unit posix - Constants - Permission bits

28.1.4.4 perm/irgrp
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/iwgrp,  Next: Unit posix - Constants - Permission bits - perm/ixgrp,  Prev: Unit posix - Constants - Permission bits - perm/irgrp,  Up: Unit posix - Constants - Permission bits

28.1.4.5 perm/iwgrp
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/ixgrp,  Next: Unit posix - Constants - Permission bits - perm/iroth,  Prev: Unit posix - Constants - Permission bits - perm/iwgrp,  Up: Unit posix - Constants - Permission bits

28.1.4.6 perm/ixgrp
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/iroth,  Next: Unit posix - Constants - Permission bits - perm/iwoth,  Prev: Unit posix - Constants - Permission bits - perm/ixgrp,  Up: Unit posix - Constants - Permission bits

28.1.4.7 perm/iroth
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/iwoth,  Next: Unit posix - Constants - Permission bits - perm/ixoth,  Prev: Unit posix - Constants - Permission bits - perm/iroth,  Up: Unit posix - Constants - Permission bits

28.1.4.8 perm/iwoth
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/ixoth,  Next: Unit posix - Constants - Permission bits - perm/irwxu,  Prev: Unit posix - Constants - Permission bits - perm/iwoth,  Up: Unit posix - Constants - Permission bits

28.1.4.9 perm/ixoth
...................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/irwxu,  Next: Unit posix - Constants - Permission bits - perm/irwxg,  Prev: Unit posix - Constants - Permission bits - perm/ixoth,  Up: Unit posix - Constants - Permission bits

28.1.4.10 perm/irwxu
....................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/irwxg,  Next: Unit posix - Constants - Permission bits - perm/irwxo,  Prev: Unit posix - Constants - Permission bits - perm/irwxu,  Up: Unit posix - Constants - Permission bits

28.1.4.11 perm/irwxg
....................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/irwxo,  Next: Unit posix - Constants - Permission bits - perm/isvtx,  Prev: Unit posix - Constants - Permission bits - perm/irwxg,  Up: Unit posix - Constants - Permission bits

28.1.4.12 perm/irwxo
....................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/isvtx,  Next: Unit posix - Constants - Permission bits - perm/isuid,  Prev: Unit posix - Constants - Permission bits - perm/irwxo,  Up: Unit posix - Constants - Permission bits

28.1.4.13 perm/isvtx
....................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/isuid,  Next: Unit posix - Constants - Permission bits - perm/isgid,  Prev: Unit posix - Constants - Permission bits - perm/isvtx,  Up: Unit posix - Constants - Permission bits

28.1.4.14 perm/isuid
....................


File: chicken.info,  Node: Unit posix - Constants - Permission bits - perm/isgid,  Prev: Unit posix - Constants - Permission bits - perm/isuid,  Up: Unit posix - Constants - Permission bits

28.1.4.15 perm/isgid
....................


File: chicken.info,  Node: Unit posix - Directories,  Next: Unit posix - Pipes,  Prev: Unit posix - Constants,  Up: Unit posix

28.2 Directories
================

* Menu:

* Unit posix - Directories - change-directory::
* Unit posix - Directories - current-directory::
* Unit posix - Directories - create-directory::
* Unit posix - Directories - delete-directory::
* Unit posix - Directories - directory::
* Unit posix - Directories - directory?::
* Unit posix - Directories - glob::
* Unit posix - Directories - canonical-path::
* Unit posix - Directories - set-root-directory!::


File: chicken.info,  Node: Unit posix - Directories - change-directory,  Next: Unit posix - Directories - current-directory,  Up: Unit posix - Directories

28.2.1 change-directory
-----------------------


[procedure] (change-directory NAME)
 Changes the current working directory to `NAME'.


File: chicken.info,  Node: Unit posix - Directories - current-directory,  Next: Unit posix - Directories - create-directory,  Prev: Unit posix - Directories - change-directory,  Up: Unit posix - Directories

28.2.2 current-directory
------------------------


[procedure] (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)'.


File: chicken.info,  Node: Unit posix - Directories - create-directory,  Next: Unit posix - Directories - delete-directory,  Prev: Unit posix - Directories - current-directory,  Up: Unit posix - Directories

28.2.3 create-directory
-----------------------


[procedure] (create-directory NAME #!optional PARENTS?)
 Creates a directory with the pathname `NAME'.  If the `PARENTS?'
argument is given and not false, any nonextant parent directories are
also created.


File: chicken.info,  Node: Unit posix - Directories - delete-directory,  Next: Unit posix - Directories - directory,  Prev: Unit posix - Directories - create-directory,  Up: Unit posix - Directories

28.2.4 delete-directory
-----------------------


[procedure] (delete-directory NAME)
 Deletes the directory with the pathname `NAME'. The directory has to
be empty.


File: chicken.info,  Node: Unit posix - Directories - directory,  Next: Unit posix - Directories - directory?,  Prev: Unit posix - Directories - delete-directory,  Up: Unit posix - Directories

28.2.5 directory
----------------


[procedure] (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)'). Files beginning with `.' are included only if
`SHOW-DOTFILES?' is given and not `#f'.


File: chicken.info,  Node: Unit posix - Directories - directory?,  Next: Unit posix - Directories - glob,  Prev: Unit posix - Directories - directory,  Up: Unit posix - Directories

28.2.6 directory?
-----------------


[procedure] (directory? NAME)
 Returns `#t' if there exists a file with the name `NAME' and if that
file is a directory, or `#f' otherwise.


File: chicken.info,  Node: Unit posix - Directories - glob,  Next: Unit posix - Directories - canonical-path,  Prev: Unit posix - Directories - directory?,  Up: Unit posix - Directories

28.2.7 glob
-----------


[procedure] (glob PATTERN1 ...)
 Returns a list of the pathnames of all existing files matching
`PATTERN1 ...', which should be strings containing the usual
file-patterns (with `*' matching zero or more characters and `?'
matching zero or one character).  Bug: wildcard characters are only
recognized in the rightmost portion of the pattern.


File: chicken.info,  Node: Unit posix - Directories - canonical-path,  Next: Unit posix - Directories - set-root-directory!,  Prev: Unit posix - Directories - glob,  Up: Unit posix - Directories

28.2.8 canonical-path
---------------------


[procedure] (canonical-path NAME)
 Returns a canonical path for `NAME', which should be a string
containing a path-or-filename.  The string returned by
`canonical-path' is OS dependent; it may be quoted and used in a shell
on the calling machine. (Quoting is suggested as shell special
characters, including space, are not escaped.)  However, all path
separators and prefixes are handled in an OS independent fashion.  Any
appearance of `/' below imply `\\' is also handled.

The prefix for `NAME' determines what path to prepend.  If `NAME'
begins with a `"~/"', this prefix is stripped and the user's  home
directory is added.  If beginning with `/' or a DRIVE-LETTER:\\
combination, no additional path is added.  Otherwise, the current
directory and separator are added.  All relative path elements and
duplicate separators are processed and removed.  If `NAME' ends with a
`/' or is empty, the appropriate slash is appended to the tail.

   No directories or files are actually tested for existence; this
procedure only canonicalises path syntax.


File: chicken.info,  Node: Unit posix - Directories - set-root-directory!,  Prev: Unit posix - Directories - canonical-path,  Up: Unit posix - Directories

28.2.9 set-root-directory!
--------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Pipes,  Next: Unit posix - Fifos,  Prev: Unit posix - Directories,  Up: Unit posix

28.3 Pipes
==========

* Menu:

* Unit posix - Pipes - call-with-input-pipe::
* Unit posix - Pipes - call-with-output-pipe::
* Unit posix - Pipes - close-input-pipe::
* Unit posix - Pipes - close-output-pipe::
* Unit posix - Pipes - create-pipe::
* Unit posix - Pipes - open-input-pipe::
* Unit posix - Pipes - open-output-pipe::
* Unit posix - Pipes - pipe/buf::
* Unit posix - Pipes - with-input-from-pipe::
* Unit posix - Pipes - with-output-to-pipe::


File: chicken.info,  Node: Unit posix - Pipes - call-with-input-pipe,  Next: Unit posix - Pipes - call-with-output-pipe,  Up: Unit posix - Pipes

28.3.1 call-with-input-pipe
---------------------------


File: chicken.info,  Node: Unit posix - Pipes - call-with-output-pipe,  Next: Unit posix - Pipes - close-input-pipe,  Prev: Unit posix - Pipes - call-with-input-pipe,  Up: Unit posix - Pipes

28.3.2 call-with-output-pipe
----------------------------


[procedure] (call-with-input-pipe CMDLINE PROC [MODE])
[procedure] (call-with-output-pipe CMDLINE PROC [MODE])
 Call `PROC' with a single argument: a input- or output port for a pipe
connected to the subprocess named in `CMDLINE'. If `PROC' returns
normally, the pipe is closed and any result values are returned.


File: chicken.info,  Node: Unit posix - Pipes - close-input-pipe,  Next: Unit posix - Pipes - close-output-pipe,  Prev: Unit posix - Pipes - call-with-output-pipe,  Up: Unit posix - Pipes

28.3.3 close-input-pipe
-----------------------


File: chicken.info,  Node: Unit posix - Pipes - close-output-pipe,  Next: Unit posix - Pipes - create-pipe,  Prev: Unit posix - Pipes - close-input-pipe,  Up: Unit posix - Pipes

28.3.4 close-output-pipe
------------------------


[procedure] (close-input-pipe PORT)
[procedure] (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.


File: chicken.info,  Node: Unit posix - Pipes - create-pipe,  Next: Unit posix - Pipes - open-input-pipe,  Prev: Unit posix - Pipes - close-output-pipe,  Up: Unit posix - Pipes

28.3.5 create-pipe
------------------


[procedure] (create-pipe)
 The fundamental pipe-creation operator. Calls the C function `pipe()'
and returns 2 values: the file-descriptors of the input- and
output-ends of the pipe.


File: chicken.info,  Node: Unit posix - Pipes - open-input-pipe,  Next: Unit posix - Pipes - open-output-pipe,  Prev: Unit posix - Pipes - create-pipe,  Up: Unit posix - Pipes

28.3.6 open-input-pipe
----------------------


[procedure] (open-input-pipe CMDLINE [MODE])
 Spawns a subprocess with the command-line string `CMDLINE' and returns
a port, from which the output of the process can be read. If `MODE' is
specified, it should be the keyword `#:text' (the default) or
`#:binary'.


File: chicken.info,  Node: Unit posix - Pipes - open-output-pipe,  Next: Unit posix - Pipes - pipe/buf,  Prev: Unit posix - Pipes - open-input-pipe,  Up: Unit posix - Pipes

28.3.7 open-output-pipe
-----------------------


[procedure] (open-output-pipe CMDLINE [MODE])
 Spawns a subprocess with the command-line string `CMDLINE' and returns
a port. Anything written to that port is treated as the input for the
process.  If `MODE' is specified, it should be the keyword `#:text'
(the default) or `#:binary'.


File: chicken.info,  Node: Unit posix - Pipes - pipe/buf,  Next: Unit posix - Pipes - with-input-from-pipe,  Prev: Unit posix - Pipes - open-output-pipe,  Up: Unit posix - Pipes

28.3.8 pipe/buf
---------------

This variable contains the maximal number of bytes that can be written
atomically into a pipe or FIFO.


File: chicken.info,  Node: Unit posix - Pipes - with-input-from-pipe,  Next: Unit posix - Pipes - with-output-to-pipe,  Prev: Unit posix - Pipes - pipe/buf,  Up: Unit posix - Pipes

28.3.9 with-input-from-pipe
---------------------------


File: chicken.info,  Node: Unit posix - Pipes - with-output-to-pipe,  Prev: Unit posix - Pipes - with-input-from-pipe,  Up: Unit posix - Pipes

28.3.10 with-output-to-pipe
---------------------------


[procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
[procedure] (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
      ) ) )


File: chicken.info,  Node: Unit posix - Fifos,  Next: Unit posix - File descriptors and low-level I/O,  Prev: Unit posix - Pipes,  Up: Unit posix

28.4 Fifos
==========

* Menu:

* Unit posix - Fifos - create-fifo::
* Unit posix - Fifos - fifo?::


File: chicken.info,  Node: Unit posix - Fifos - create-fifo,  Next: Unit posix - Fifos - fifo?,  Up: Unit posix - Fifos

28.4.1 create-fifo
------------------


[procedure] (create-fifo FILENAME [MODE])
 Creates a FIFO with the name `FILENAME' and the permission bits
`MODE', which defaults to

      [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)


File: chicken.info,  Node: Unit posix - Fifos - fifo?,  Prev: Unit posix - Fifos - create-fifo,  Up: Unit posix - Fifos

28.4.2 fifo?
------------


[procedure] (fifo? FILENAME)
 Returns `#t' if the file with the name `FILENAME' names a FIFO.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O,  Next: Unit posix - Retrieving file attributes,  Prev: Unit posix - Fifos,  Up: Unit posix

28.5 File descriptors and low-level I/O
=======================================

* Menu:

* Unit posix - File descriptors and low-level I/O - duplicate-fileno::
* Unit posix - File descriptors and low-level I/O - file-close::
* Unit posix - File descriptors and low-level I/O - file-open::
* Unit posix - File descriptors and low-level I/O - file-mkstemp::
* Unit posix - File descriptors and low-level I/O - file-read::
* Unit posix - File descriptors and low-level I/O - file-select::
* Unit posix - File descriptors and low-level I/O - file-write::
* Unit posix - File descriptors and low-level I/O - file-control::
* Unit posix - File descriptors and low-level I/O - open-input-file*::
* Unit posix - File descriptors and low-level I/O - open-output-file*::
* Unit posix - File descriptors and low-level I/O - port->fileno::


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - duplicate-fileno,  Next: Unit posix - File descriptors and low-level I/O - file-close,  Up: Unit posix - File descriptors and low-level I/O

28.5.1 duplicate-fileno
-----------------------


[procedure] (duplicate-fileno OLD [NEW])
 If `NEW' is given, then the file-descriptor `NEW' is opened to access
the file with the file-descriptor `OLD'. Otherwise a fresh
file-descriptor accessing the same file as `OLD' is returned.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-close,  Next: Unit posix - File descriptors and low-level I/O - file-open,  Prev: Unit posix - File descriptors and low-level I/O - duplicate-fileno,  Up: Unit posix - File descriptors and low-level I/O

28.5.2 file-close
-----------------


[procedure] (file-close FILENO)
 Closes the input/output file with the file-descriptor `FILENO'.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-open,  Next: Unit posix - File descriptors and low-level I/O - file-mkstemp,  Prev: Unit posix - File descriptors and low-level I/O - file-close,  Up: Unit posix - File descriptors and low-level I/O

28.5.3 file-open
----------------


[procedure] (file-open FILENAME FLAGS [MODE])
 Opens the file specified with the string `FILENAME' and open-flags
`FLAGS' using the C function `open()'. On success a file-descriptor for
the opened file is returned.  `FLAGS' should be a bitmask containing
one or more of the `open/...' values ored together using `bitwise-ior'
(or simply added together).  The optional `MODE' should be a bitmask
composed of one or more permission values like `perm/irusr' and is only
relevant when a new file is created. The default mode is `perm/irwxu |
perm/irgrp | perm/iroth'.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-mkstemp,  Next: Unit posix - File descriptors and low-level I/O - file-read,  Prev: Unit posix - File descriptors and low-level I/O - file-open,  Up: Unit posix - File descriptors and low-level I/O

28.5.4 file-mkstemp
-------------------


[procedure] (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)))


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-read,  Next: Unit posix - File descriptors and low-level I/O - file-select,  Prev: Unit posix - File descriptors and low-level I/O - file-mkstemp,  Up: Unit posix - File descriptors and low-level I/O

28.5.5 file-read
----------------


[procedure] (file-read FILENO SIZE [BUFFER])
 Reads `SIZE' bytes from the file with the file-descriptor `FILENO'.
If a string or bytevector is passed in the optional argument `BUFFER',
then this string will be destructively modified to contain the read
data. This procedure returns a list with two values: the buffer
containing the data and the number of bytes read.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-select,  Next: Unit posix - File descriptors and low-level I/O - file-write,  Prev: Unit posix - File descriptors and low-level I/O - file-read,  Up: Unit posix - File descriptors and low-level I/O

28.5.6 file-select
------------------


[procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])
 Waits until any of the file-descriptors given in the lists
`READFDLIST' and `WRITEFDLIST' is ready for input or output,
respectively. If the optional argument `TIMEOUT' is given and not
false, then it should specify the number of seconds after which the
wait is to be aborted (the value may be a floating point number). 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 `()'.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-write,  Next: Unit posix - File descriptors and low-level I/O - file-control,  Prev: Unit posix - File descriptors and low-level I/O - file-select,  Up: Unit posix - File descriptors and low-level I/O

28.5.7 file-write
-----------------


[procedure] (file-write FILENO BUFFER [SIZE])
 Writes the contents of the string or bytevector `BUFFER' into the file
with the file-descriptor `FILENO'. If the optional argument `SIZE' is
given, then only the specified number of bytes are written.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - file-control,  Next: Unit posix - File descriptors and low-level I/O - open-input-file*,  Prev: Unit posix - File descriptors and low-level I/O - file-write,  Up: Unit posix - File descriptors and low-level I/O

28.5.8 file-control
-------------------


[procedure] (file-control FILENO COMMAND [ARGUMENT])
 Performs the fcntl operation `COMMAND' with the given `FILENO' and
optional `ARGUMENT'. The return value is meaningful depending on the
`COMMAND'.


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - open-input-file*,  Next: Unit posix - File descriptors and low-level I/O - open-output-file*,  Prev: Unit posix - File descriptors and low-level I/O - file-control,  Up: Unit posix - File descriptors and low-level I/O

28.5.9 open-input-file*
-----------------------


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - open-output-file*,  Next: Unit posix - File descriptors and low-level I/O - port->fileno,  Prev: Unit posix - File descriptors and low-level I/O - open-input-file*,  Up: Unit posix - File descriptors and low-level I/O

28.5.10 open-output-file*
-------------------------


[procedure] (open-input-file* FILENO [OPENMODE])
[procedure] (open-output-file* FILENO [OPENMODE])
 Opens file for the file-descriptor `FILENO' for input or output and
returns a port.  `FILENO' should be a positive exact integer.
`OPENMODE' specifies an additional mode for opening the file (currently
only the keyword `#:append' is supported, which opens an output-file
for appending).


File: chicken.info,  Node: Unit posix - File descriptors and low-level I/O - port->fileno,  Prev: Unit posix - File descriptors and low-level I/O - open-output-file*,  Up: Unit posix - File descriptors and low-level I/O

28.5.11 port->fileno
--------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Retrieving file attributes,  Next: Unit posix - Changing file attributes,  Prev: Unit posix - File descriptors and low-level I/O,  Up: Unit posix

28.6 Retrieving file attributes
===============================

* Menu:

* Unit posix - Retrieving file attributes - file-access-time::
* Unit posix - Retrieving file attributes - file-change-time::
* Unit posix - Retrieving file attributes - file-modification-time::
* Unit posix - Retrieving file attributes - file-stat::
* Unit posix - Retrieving file attributes - file-position::
* Unit posix - Retrieving file attributes - file-size::
* Unit posix - Retrieving file attributes - regular-file?::
* Unit posix - Retrieving file attributes - file-owner::
* Unit posix - Retrieving file attributes - file-permissions::
* Unit posix - Retrieving file attributes - file-read-access?::
* Unit posix - Retrieving file attributes - file-write-access?::
* Unit posix - Retrieving file attributes - file-execute-access?::
* Unit posix - Retrieving file attributes - stat-regular?::
* Unit posix - Retrieving file attributes - stat-directory?::
* Unit posix - Retrieving file attributes - stat-char-device?::
* Unit posix - Retrieving file attributes - stat-block-device?::
* Unit posix - Retrieving file attributes - stat-fifo?::
* Unit posix - Retrieving file attributes - stat-symlink?::
* Unit posix - Retrieving file attributes - stat-socket?::


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-access-time,  Next: Unit posix - Retrieving file attributes - file-change-time,  Up: Unit posix - Retrieving file attributes

28.6.1 file-access-time
-----------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-change-time,  Next: Unit posix - Retrieving file attributes - file-modification-time,  Prev: Unit posix - Retrieving file attributes - file-access-time,  Up: Unit posix - Retrieving file attributes

28.6.2 file-change-time
-----------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-modification-time,  Next: Unit posix - Retrieving file attributes - file-stat,  Prev: Unit posix - Retrieving file attributes - file-change-time,  Up: Unit posix - Retrieving file attributes

28.6.3 file-modification-time
-----------------------------


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


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-stat,  Next: Unit posix - Retrieving file attributes - file-position,  Prev: Unit posix - Retrieving file attributes - file-modification-time,  Up: Unit posix - Retrieving file attributes

28.6.4 file-stat
----------------


[procedure] (file-stat FILE [LINK])
 Returns a 13-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', device id, device type
(for special file inode, blocksize and blocks allocated.  On Windows
systems the last 4 values are undefined.  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 not
resolved). Note that for very large files, the `file-size' value may be
an inexact integer.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-position,  Next: Unit posix - Retrieving file attributes - file-size,  Prev: Unit posix - Retrieving file attributes - file-stat,  Up: Unit posix - Retrieving file attributes

28.6.5 file-position
--------------------


[procedure] (file-position FILE)
 Returns the current file position of `FILE', which should be a port or
a file-descriptor.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-size,  Next: Unit posix - Retrieving file attributes - regular-file?,  Prev: Unit posix - Retrieving file attributes - file-position,  Up: Unit posix - Retrieving file attributes

28.6.6 file-size
----------------


[procedure] (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. Note that for very large files, `file-size' may return an
inexact integer.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - regular-file?,  Next: Unit posix - Retrieving file attributes - file-owner,  Prev: Unit posix - Retrieving file attributes - file-size,  Up: Unit posix - Retrieving file attributes

28.6.7 regular-file?
--------------------


[procedure] (regular-file? FILENAME)
 Returns true, if `FILENAME' names a regular file (not a directory or
symbolic link).


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-owner,  Next: Unit posix - Retrieving file attributes - file-permissions,  Prev: Unit posix - Retrieving file attributes - regular-file?,  Up: Unit posix - Retrieving file attributes

28.6.8 file-owner
-----------------


[procedure] (file-owner FILE)
 Returns the user-id of `FILE'.  `FILE' may be a filename or a
file-descriptor.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-permissions,  Next: Unit posix - Retrieving file attributes - file-read-access?,  Prev: Unit posix - Retrieving file attributes - file-owner,  Up: Unit posix - Retrieving file attributes

28.6.9 file-permissions
-----------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-read-access?,  Next: Unit posix - Retrieving file attributes - file-write-access?,  Prev: Unit posix - Retrieving file attributes - file-permissions,  Up: Unit posix - Retrieving file attributes

28.6.10 file-read-access?
-------------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-write-access?,  Next: Unit posix - Retrieving file attributes - file-execute-access?,  Prev: Unit posix - Retrieving file attributes - file-read-access?,  Up: Unit posix - Retrieving file attributes

28.6.11 file-write-access?
--------------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - file-execute-access?,  Next: Unit posix - Retrieving file attributes - stat-regular?,  Prev: Unit posix - Retrieving file attributes - file-write-access?,  Up: Unit posix - Retrieving file attributes

28.6.12 file-execute-access?
----------------------------


[procedure] (file-read-access? FILENAME)
[procedure] (file-write-access? FILENAME)
[procedure] (file-execute-access? FILENAME)
 These procedures return `#t' if the current user has read, write or
execute permissions on the file named `FILENAME'.


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-regular?,  Next: Unit posix - Retrieving file attributes - stat-directory?,  Prev: Unit posix - Retrieving file attributes - file-execute-access?,  Up: Unit posix - Retrieving file attributes

28.6.13 stat-regular?
---------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-directory?,  Next: Unit posix - Retrieving file attributes - stat-char-device?,  Prev: Unit posix - Retrieving file attributes - stat-regular?,  Up: Unit posix - Retrieving file attributes

28.6.14 stat-directory?
-----------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-char-device?,  Next: Unit posix - Retrieving file attributes - stat-block-device?,  Prev: Unit posix - Retrieving file attributes - stat-directory?,  Up: Unit posix - Retrieving file attributes

28.6.15 stat-char-device?
-------------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-block-device?,  Next: Unit posix - Retrieving file attributes - stat-fifo?,  Prev: Unit posix - Retrieving file attributes - stat-char-device?,  Up: Unit posix - Retrieving file attributes

28.6.16 stat-block-device?
--------------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-fifo?,  Next: Unit posix - Retrieving file attributes - stat-symlink?,  Prev: Unit posix - Retrieving file attributes - stat-block-device?,  Up: Unit posix - Retrieving file attributes

28.6.17 stat-fifo?
------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-symlink?,  Next: Unit posix - Retrieving file attributes - stat-socket?,  Prev: Unit posix - Retrieving file attributes - stat-fifo?,  Up: Unit posix - Retrieving file attributes

28.6.18 stat-symlink?
---------------------


File: chicken.info,  Node: Unit posix - Retrieving file attributes - stat-socket?,  Prev: Unit posix - Retrieving file attributes - stat-symlink?,  Up: Unit posix - Retrieving file attributes

28.6.19 stat-socket?
--------------------


[procedure] (stat-regular? FILENAME)
[procedure] (stat-directory? FILENAME)
[procedure] (stat-char-device? FILENAME)
[procedure] (stat-block-device? FILENAME)
[procedure] (stat-fifo? FILENAME)
[procedure] (stat-symlink? FILENAME)
[procedure] (stat-socket? FILENAME)
 These procedures return `#t' if the `FILENAME' given is of the
appropriate type.


File: chicken.info,  Node: Unit posix - Changing file attributes,  Next: Unit posix - Processes,  Prev: Unit posix - Retrieving file attributes,  Up: Unit posix

28.7 Changing file attributes
=============================

* Menu:

* Unit posix - Changing file attributes - file-truncate::
* Unit posix - Changing file attributes - set-file-position!::
* Unit posix - Changing file attributes - change-file-mode::
* Unit posix - Changing file attributes - change-file-owner::


File: chicken.info,  Node: Unit posix - Changing file attributes - file-truncate,  Next: Unit posix - Changing file attributes - set-file-position!,  Up: Unit posix - Changing file attributes

28.7.1 file-truncate
--------------------


[procedure] (file-truncate FILE OFFSET)
 Truncates the file `FILE' to the length `OFFSET', which should be an
integer. If the file-size is smaller or equal to `OFFSET' then nothing
is done.  `FILE' should be a filename or a file-descriptor.


File: chicken.info,  Node: Unit posix - Changing file attributes - set-file-position!,  Next: Unit posix - Changing file attributes - change-file-mode,  Prev: Unit posix - Changing file attributes - file-truncate,  Up: Unit posix - Changing file attributes

28.7.2 set-file-position!
-------------------------


[procedure] (set-file-position! FILE POSITION [WHENCE])
[procedure] (set! (file-position FILE) POSITION)
 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)'


File: chicken.info,  Node: Unit posix - Changing file attributes - change-file-mode,  Next: Unit posix - Changing file attributes - change-file-owner,  Prev: Unit posix - Changing file attributes - set-file-position!,  Up: Unit posix - Changing file attributes

28.7.3 change-file-mode
-----------------------


[procedure] (change-file-mode FILENAME MODE)
 Changes the current file mode of the file named `FILENAME' to `MODE'
using the `chmod()' system call.  The `perm/...' variables contain the
various permission bits and can be combinded with the `bitwise-ior'
procedure.


File: chicken.info,  Node: Unit posix - Changing file attributes - change-file-owner,  Prev: Unit posix - Changing file attributes - change-file-mode,  Up: Unit posix - Changing file attributes

28.7.4 change-file-owner
------------------------


[procedure] (change-file-owner FILENAME UID GID)
 Changes the owner information of the file named `FILENAME' to the
user- and group-ids `UID' and `GID' (which should be exact integers)
using the `chown()' system call.


File: chicken.info,  Node: Unit posix - Processes,  Next: Unit posix - Hard and symbolic links,  Prev: Unit posix - Changing file attributes,  Up: Unit posix

28.8 Processes
==============

* Menu:

* Unit posix - Processes - current-process-id::
* Unit posix - Processes - parent-process-id::
* Unit posix - Processes - process-group-id::
* Unit posix - Processes - process-execute::
* Unit posix - Processes - process-fork::
* Unit posix - Processes - process-run::
* Unit posix - Processes - process-signal::
* Unit posix - Processes - process-wait::
* Unit posix - Processes - process::
* Unit posix - Processes - process*::
* Unit posix - Processes - sleep::
* Unit posix - Processes - create-session::


File: chicken.info,  Node: Unit posix - Processes - current-process-id,  Next: Unit posix - Processes - parent-process-id,  Up: Unit posix - Processes

28.8.1 current-process-id
-------------------------


[procedure] (current-process-id)
 Returns the process ID of the current process.


File: chicken.info,  Node: Unit posix - Processes - parent-process-id,  Next: Unit posix - Processes - process-group-id,  Prev: Unit posix - Processes - current-process-id,  Up: Unit posix - Processes

28.8.2 parent-process-id
------------------------


[procedure] (parent-process-id)
 Returns the process ID of the parent of the current process.


File: chicken.info,  Node: Unit posix - Processes - process-group-id,  Next: Unit posix - Processes - process-execute,  Prev: Unit posix - Processes - parent-process-id,  Up: Unit posix - Processes

28.8.3 process-group-id
-----------------------


[procedure] (process-group-id PID)
 Returns the process group ID of the process specified by `PID'.


File: chicken.info,  Node: Unit posix - Processes - process-execute,  Next: Unit posix - Processes - process-fork,  Prev: Unit posix - Processes - process-group-id,  Up: Unit posix - Processes

28.8.4 process-execute
----------------------


[procedure] (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 supplied, 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.


File: chicken.info,  Node: Unit posix - Processes - process-fork,  Next: Unit posix - Processes - process-run,  Prev: Unit posix - Processes - process-execute,  Up: Unit posix - Processes

28.8.5 process-fork
-------------------


[procedure] (process-fork [THUNK])
 Creates a new child process with the UNIX system call `fork()'.
Returns either the PID of the child process or 0. If `THUNK' is given,
then the child process calls it as a procedure with no arguments and
terminates.


File: chicken.info,  Node: Unit posix - Processes - process-run,  Next: Unit posix - Processes - process-signal,  Prev: Unit posix - Processes - process-fork,  Up: Unit posix - Processes

28.8.6 process-run
------------------


[procedure] (process-run COMMANDLINE])
[procedure] (process-run COMMAND ARGUMENT-LIST)
 Creates a new child process. The PID of the new process is returned.

   * The single parameter version passes the `COMMANDLINE' to the
     system shell, so usual argument expansion can take place.

   * The multiple parameter version directly invokes the `COMMAND' with
     the `ARGUMENT-LIST'.



File: chicken.info,  Node: Unit posix - Processes - process-signal,  Next: Unit posix - Processes - process-wait,  Prev: Unit posix - Processes - process-run,  Up: Unit posix - Processes

28.8.7 process-signal
---------------------


[procedure] (process-signal PID [SIGNAL])
 Sends `SIGNAL' to the process with the id `PID' using the UNIX system
call `kill()'. `SIGNAL' defaults to the value of the variable
`signal/term'.


File: chicken.info,  Node: Unit posix - Processes - process-wait,  Next: Unit posix - Processes - process,  Prev: Unit posix - Processes - process-signal,  Up: Unit posix - Processes

28.8.8 process-wait
-------------------


[procedure] (process-wait [PID [NOHANG]])
 Suspends the current process until the child process with the id `PID'
has terminated using the UNIX system call `waitpid()'. If `PID' is not
given, then this procedure waits for any child process. If `NOHANG' is
given and not `#f' then the current process is not suspended.  This
procedure returns three values:

   * `PID' or 0, if `NOHANG' is true and the child process has not
     terminated yet.

   * `#t' if the process exited normally or `#f' otherwise.

   * either the exit status, if the process terminated normally or the
     signal number that terminated/stopped the process.



File: chicken.info,  Node: Unit posix - Processes - process,  Next: Unit posix - Processes - process*,  Prev: Unit posix - Processes - process-wait,  Up: Unit posix - Processes

28.8.9 process
--------------


[procedure] (process COMMANDLINE)
[procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
 Creates 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.

   * The single parameter version passes the string `COMMANDLINE' to
     the host-system's shell that is invoked as a subprocess.

   * The multiple parameter version directly invokes the `COMMAND' as a
     subprocess. The `ARGUMENT-LIST' is directly passed, as is
     `ENVIRONMENT-LIST'.

Not using the shell may be preferrable for security reasons.


File: chicken.info,  Node: Unit posix - Processes - process*,  Next: Unit posix - Processes - sleep,  Prev: Unit posix - Processes - process,  Up: Unit posix - Processes

28.8.10 process*
----------------


[procedure] (process* COMMANDLINE)
[procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
 Like `process' but returns 4 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, the
process-id of the started sub-process, and an input port from which
data written by the sub-process to `stderr' can be read.


File: chicken.info,  Node: Unit posix - Processes - sleep,  Next: Unit posix - Processes - create-session,  Prev: Unit posix - Processes - process*,  Up: Unit posix - Processes

28.8.11 sleep
-------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Processes - create-session,  Prev: Unit posix - Processes - sleep,  Up: Unit posix - Processes

28.8.12 create-session
----------------------


[procedure] (create-session)
 Creates a new session if the calling process is not a process group
leader and returns the session ID.


File: chicken.info,  Node: Unit posix - Hard and symbolic links,  Next: Unit posix - Retrieving user & group information,  Prev: Unit posix - Processes,  Up: Unit posix

28.9 Hard and symbolic links
============================

* Menu:

* Unit posix - Hard and symbolic links - symbolic-link?::
* Unit posix - Hard and symbolic links - create-symbolic-link::
* Unit posix - Hard and symbolic links - read-symbolic-link::
* Unit posix - Hard and symbolic links - file-link::


File: chicken.info,  Node: Unit posix - Hard and symbolic links - symbolic-link?,  Next: Unit posix - Hard and symbolic links - create-symbolic-link,  Up: Unit posix - Hard and symbolic links

28.9.1 symbolic-link?
---------------------


[procedure] (symbolic-link? FILENAME)
 Returns true, if `FILENAME' names a symbolic link.


File: chicken.info,  Node: Unit posix - Hard and symbolic links - create-symbolic-link,  Next: Unit posix - Hard and symbolic links - read-symbolic-link,  Prev: Unit posix - Hard and symbolic links - symbolic-link?,  Up: Unit posix - Hard and symbolic links

28.9.2 create-symbolic-link
---------------------------


[procedure] (create-symbolic-link OLDNAME NEWNAME)
 Creates a symbolic link with the filename `NEWNAME' that points to the
file named `OLDNAME'.


File: chicken.info,  Node: Unit posix - Hard and symbolic links - read-symbolic-link,  Next: Unit posix - Hard and symbolic links - file-link,  Prev: Unit posix - Hard and symbolic links - create-symbolic-link,  Up: Unit posix - Hard and symbolic links

28.9.3 read-symbolic-link
-------------------------


[procedure] (read-symbolic-link FILENAME)
 Returns the filename to which the symbolic link `FILENAME' points.


File: chicken.info,  Node: Unit posix - Hard and symbolic links - file-link,  Prev: Unit posix - Hard and symbolic links - read-symbolic-link,  Up: Unit posix - Hard and symbolic links

28.9.4 file-link
----------------


[procedure] (file-link OLDNAME NEWNAME)
 Creates a hard link from `OLDNAME' to `NEWNAME' (both strings).


File: chicken.info,  Node: Unit posix - Retrieving user & group information,  Next: Unit posix - Changing user & group information,  Prev: Unit posix - Hard and symbolic links,  Up: Unit posix

28.10 Retrieving user & group information
=========================================

* Menu:

* Unit posix - Retrieving user & group information - current-user-id::
* Unit posix - Retrieving user & group information - current-effective-user-id::
* Unit posix - Retrieving user & group information - user-information::
* Unit posix - Retrieving user & group information - current-group-id::
* Unit posix - Retrieving user & group information - current-effective-group-id::
* Unit posix - Retrieving user & group information - group-information::
* Unit posix - Retrieving user & group information - get-groups::


File: chicken.info,  Node: Unit posix - Retrieving user & group information - current-user-id,  Next: Unit posix - Retrieving user & group information - current-effective-user-id,  Up: Unit posix - Retrieving user & group information

28.10.1 current-user-id
-----------------------


[procedure] (current-user-id)
[setter] (set! (current-user-id) UID)
 Get or set the real user-id of the current process.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - current-effective-user-id,  Next: Unit posix - Retrieving user & group information - user-information,  Prev: Unit posix - Retrieving user & group information - current-user-id,  Up: Unit posix - Retrieving user & group information

28.10.2 current-effective-user-id
---------------------------------


[procedure] (current-effective-user-id)
[setter] (set! (current-effective-user-id) UID)
 Get or set the effective user-id of the current process.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - user-information,  Next: Unit posix - Retrieving user & group information - current-group-id,  Prev: Unit posix - Retrieving user & group information - current-effective-user-id,  Up: Unit posix - Retrieving user & group information

28.10.3 user-information
------------------------


[procedure] (user-information USER [AS-VECTOR])
 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. When
`AS-VECTOR' is `#t' a vector of 7 elements is returned instead of a
list. If no user with this name or id then `#f' is returned.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - current-group-id,  Next: Unit posix - Retrieving user & group information - current-effective-group-id,  Prev: Unit posix - Retrieving user & group information - user-information,  Up: Unit posix - Retrieving user & group information

28.10.4 current-group-id
------------------------


[procedure] (current-group-id)
[setter] (set! (current-group-id) GID)
 Get or set the real group-id of the current process.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - current-effective-group-id,  Next: Unit posix - Retrieving user & group information - group-information,  Prev: Unit posix - Retrieving user & group information - current-group-id,  Up: Unit posix - Retrieving user & group information

28.10.5 current-effective-group-id
----------------------------------


[procedure] (current-effective-group-id)
[setter] (set! (current-effective-group-id) GID)
 Get or set the effective group-id of the current process. ID can be
found, then `#f' is returned.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - group-information,  Next: Unit posix - Retrieving user & group information - get-groups,  Prev: Unit posix - Retrieving user & group information - current-effective-group-id,  Up: Unit posix - Retrieving user & group information

28.10.6 group-information
-------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Retrieving user & group information - get-groups,  Prev: Unit posix - Retrieving user & group information - group-information,  Up: Unit posix - Retrieving user & group information

28.10.7 get-groups
------------------


[procedure] (get-groups)
 Returns a list with the supplementary group IDs of the current user.


File: chicken.info,  Node: Unit posix - Changing user & group information,  Next: Unit posix - Record locking,  Prev: Unit posix - Retrieving user & group information,  Up: Unit posix

28.11 Changing user & group information
=======================================

* Menu:

* Unit posix - Changing user & group information - set-groups!::
* Unit posix - Changing user & group information - initialize-groups::
* Unit posix - Changing user & group information - set-process-group-id!::


File: chicken.info,  Node: Unit posix - Changing user & group information - set-groups!,  Next: Unit posix - Changing user & group information - initialize-groups,  Up: Unit posix - Changing user & group information

28.11.1 set-groups!
-------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Changing user & group information - initialize-groups,  Next: Unit posix - Changing user & group information - set-process-group-id!,  Prev: Unit posix - Changing user & group information - set-groups!,  Up: Unit posix - Changing user & group information

28.11.2 initialize-groups
-------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Changing user & group information - set-process-group-id!,  Prev: Unit posix - Changing user & group information - initialize-groups,  Up: Unit posix - Changing user & group information

28.11.3 set-process-group-id!
-----------------------------


[procedure] (set-process-group-id! PID PGID)
[setter] (set! (process-group-id PID) PGID)
 Sets the process group ID of the process specifed by `PID' to `PGID'.


File: chicken.info,  Node: Unit posix - Record locking,  Next: Unit posix - Signal handling,  Prev: Unit posix - Changing user & group information,  Up: Unit posix

28.12 Record locking
====================

* Menu:

* Unit posix - Record locking - file-lock::
* Unit posix - Record locking - file-lock/blocking::
* Unit posix - Record locking - file-test-lock::
* Unit posix - Record locking - file-unlock::


File: chicken.info,  Node: Unit posix - Record locking - file-lock,  Next: Unit posix - Record locking - file-lock/blocking,  Up: Unit posix - Record locking

28.12.1 file-lock
-----------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Record locking - file-lock/blocking,  Next: Unit posix - Record locking - file-test-lock,  Prev: Unit posix - Record locking - file-lock,  Up: Unit posix - Record locking

28.12.2 file-lock/blocking
--------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Record locking - file-test-lock,  Next: Unit posix - Record locking - file-unlock,  Prev: Unit posix - Record locking - file-lock/blocking,  Up: Unit posix - Record locking

28.12.3 file-test-lock
----------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Record locking - file-unlock,  Prev: Unit posix - Record locking - file-test-lock,  Up: Unit posix - Record locking

28.12.4 file-unlock
-------------------


[procedure] (file-unlock LOCK)
 Unlocks the previously locked portion of a file given in `LOCK'.


File: chicken.info,  Node: Unit posix - Signal handling,  Next: Unit posix - Environment access,  Prev: Unit posix - Record locking,  Up: Unit posix

28.13 Signal handling
=====================

* Menu:

* Unit posix - Signal handling - set-alarm!::
* Unit posix - Signal handling - set-signal-handler!::
* Unit posix - Signal handling - signal-handler::
* Unit posix - Signal handling - set-signal-mask!::
* Unit posix - Signal handling - signal-mask::
* Unit posix - Signal handling - signal-masked?::
* Unit posix - Signal handling - signal-mask!::
* Unit posix - Signal handling - signal-unmask!::
* Unit posix - Signal handling - signal/term::
* Unit posix - Signal handling - signal/kill::
* Unit posix - Signal handling - signal/int::
* Unit posix - Signal handling - signal/hup::
* Unit posix - Signal handling - signal/fpe::
* Unit posix - Signal handling - signal/ill::
* Unit posix - Signal handling - signal/segv::
* Unit posix - Signal handling - signal/abrt::
* Unit posix - Signal handling - signal/trap::
* Unit posix - Signal handling - signal/quit::
* Unit posix - Signal handling - signal/alrm::
* Unit posix - Signal handling - signal/vtalrm::
* Unit posix - Signal handling - signal/prof::
* Unit posix - Signal handling - signal/io::
* Unit posix - Signal handling - signal/urg::
* Unit posix - Signal handling - signal/chld::
* Unit posix - Signal handling - signal/cont::
* Unit posix - Signal handling - signal/stop::
* Unit posix - Signal handling - signal/tstp::
* Unit posix - Signal handling - signal/pipe::
* Unit posix - Signal handling - signal/xcpu::
* Unit posix - Signal handling - signal/xfsz::
* Unit posix - Signal handling - signal/usr1::
* Unit posix - Signal handling - signal/usr2::
* Unit posix - Signal handling - signal/winch::


File: chicken.info,  Node: Unit posix - Signal handling - set-alarm!,  Next: Unit posix - Signal handling - set-signal-handler!,  Up: Unit posix - Signal handling

28.13.1 set-alarm!
------------------


[procedure] (set-alarm! SECONDS)
 Sets an internal timer to raise the `signal/alrm' after `SECONDS' are
elapsed.  You can use the `set-signal-handler!' procedure to write a
handler for this signal.


File: chicken.info,  Node: Unit posix - Signal handling - set-signal-handler!,  Next: Unit posix - Signal handling - signal-handler,  Prev: Unit posix - Signal handling - set-alarm!,  Up: Unit posix - Signal handling

28.13.2 set-signal-handler!
---------------------------


[procedure] (set-signal-handler! SIGNUM PROC)
 Establishes the procedure of one argument `PROC' as the handler for
the signal with the code `SIGNUM'. `PROC' is called with the signal
number as its sole argument. If the argument `PROC' is `#f' then any
signal handler will be removed, and the corresponding signal set to
`SIG_IGN'.

Note that is is unspecified in which thread of execution the signal
handler will be invoked.


File: chicken.info,  Node: Unit posix - Signal handling - signal-handler,  Next: Unit posix - Signal handling - set-signal-mask!,  Prev: Unit posix - Signal handling - set-signal-handler!,  Up: Unit posix - Signal handling

28.13.3 signal-handler
----------------------


[procedure] (signal-handler SIGNUM)
 Returns the signal handler for the code `SIGNUM' or `#f'.


File: chicken.info,  Node: Unit posix - Signal handling - set-signal-mask!,  Next: Unit posix - Signal handling - signal-mask,  Prev: Unit posix - Signal handling - signal-handler,  Up: Unit posix - Signal handling

28.13.4 set-signal-mask!
------------------------


[procedure] (set-signal-mask! SIGLIST)
 Sets the signal mask of the current process to block all signals given
in the list `SIGLIST'.  Signals masked in that way will not be
delivered to the current process.


File: chicken.info,  Node: Unit posix - Signal handling - signal-mask,  Next: Unit posix - Signal handling - signal-masked?,  Prev: Unit posix - Signal handling - set-signal-mask!,  Up: Unit posix - Signal handling

28.13.5 signal-mask
-------------------


[procedure] (signal-mask)
 Returns the signal mask of the current process.


File: chicken.info,  Node: Unit posix - Signal handling - signal-masked?,  Next: Unit posix - Signal handling - signal-mask!,  Prev: Unit posix - Signal handling - signal-mask,  Up: Unit posix - Signal handling

28.13.6 signal-masked?
----------------------


[procedure] (signal-masked? SIGNUM)
 Returns whether the signal for the code `SIGNUM' is currently masked.


File: chicken.info,  Node: Unit posix - Signal handling - signal-mask!,  Next: Unit posix - Signal handling - signal-unmask!,  Prev: Unit posix - Signal handling - signal-masked?,  Up: Unit posix - Signal handling

28.13.7 signal-mask!
--------------------


[procedure] (signal-mask! SIGNUM)
 Masks (blocks) the signal for the code `SIGNUM'.


File: chicken.info,  Node: Unit posix - Signal handling - signal-unmask!,  Next: Unit posix - Signal handling - signal/term,  Prev: Unit posix - Signal handling - signal-mask!,  Up: Unit posix - Signal handling

28.13.8 signal-unmask!
----------------------


[procedure] (signal-unmask! SIGNUM)
 Unmasks (unblocks) the signal for the code `SIGNUM'.


File: chicken.info,  Node: Unit posix - Signal handling - signal/term,  Next: Unit posix - Signal handling - signal/kill,  Prev: Unit posix - Signal handling - signal-unmask!,  Up: Unit posix - Signal handling

28.13.9 signal/term
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/kill,  Next: Unit posix - Signal handling - signal/int,  Prev: Unit posix - Signal handling - signal/term,  Up: Unit posix - Signal handling

28.13.10 signal/kill
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/int,  Next: Unit posix - Signal handling - signal/hup,  Prev: Unit posix - Signal handling - signal/kill,  Up: Unit posix - Signal handling

28.13.11 signal/int
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/hup,  Next: Unit posix - Signal handling - signal/fpe,  Prev: Unit posix - Signal handling - signal/int,  Up: Unit posix - Signal handling

28.13.12 signal/hup
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/fpe,  Next: Unit posix - Signal handling - signal/ill,  Prev: Unit posix - Signal handling - signal/hup,  Up: Unit posix - Signal handling

28.13.13 signal/fpe
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/ill,  Next: Unit posix - Signal handling - signal/segv,  Prev: Unit posix - Signal handling - signal/fpe,  Up: Unit posix - Signal handling

28.13.14 signal/ill
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/segv,  Next: Unit posix - Signal handling - signal/abrt,  Prev: Unit posix - Signal handling - signal/ill,  Up: Unit posix - Signal handling

28.13.15 signal/segv
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/abrt,  Next: Unit posix - Signal handling - signal/trap,  Prev: Unit posix - Signal handling - signal/segv,  Up: Unit posix - Signal handling

28.13.16 signal/abrt
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/trap,  Next: Unit posix - Signal handling - signal/quit,  Prev: Unit posix - Signal handling - signal/abrt,  Up: Unit posix - Signal handling

28.13.17 signal/trap
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/quit,  Next: Unit posix - Signal handling - signal/alrm,  Prev: Unit posix - Signal handling - signal/trap,  Up: Unit posix - Signal handling

28.13.18 signal/quit
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/alrm,  Next: Unit posix - Signal handling - signal/vtalrm,  Prev: Unit posix - Signal handling - signal/quit,  Up: Unit posix - Signal handling

28.13.19 signal/alrm
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/vtalrm,  Next: Unit posix - Signal handling - signal/prof,  Prev: Unit posix - Signal handling - signal/alrm,  Up: Unit posix - Signal handling

28.13.20 signal/vtalrm
----------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/prof,  Next: Unit posix - Signal handling - signal/io,  Prev: Unit posix - Signal handling - signal/vtalrm,  Up: Unit posix - Signal handling

28.13.21 signal/prof
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/io,  Next: Unit posix - Signal handling - signal/urg,  Prev: Unit posix - Signal handling - signal/prof,  Up: Unit posix - Signal handling

28.13.22 signal/io
------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/urg,  Next: Unit posix - Signal handling - signal/chld,  Prev: Unit posix - Signal handling - signal/io,  Up: Unit posix - Signal handling

28.13.23 signal/urg
-------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/chld,  Next: Unit posix - Signal handling - signal/cont,  Prev: Unit posix - Signal handling - signal/urg,  Up: Unit posix - Signal handling

28.13.24 signal/chld
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/cont,  Next: Unit posix - Signal handling - signal/stop,  Prev: Unit posix - Signal handling - signal/chld,  Up: Unit posix - Signal handling

28.13.25 signal/cont
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/stop,  Next: Unit posix - Signal handling - signal/tstp,  Prev: Unit posix - Signal handling - signal/cont,  Up: Unit posix - Signal handling

28.13.26 signal/stop
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/tstp,  Next: Unit posix - Signal handling - signal/pipe,  Prev: Unit posix - Signal handling - signal/stop,  Up: Unit posix - Signal handling

28.13.27 signal/tstp
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/pipe,  Next: Unit posix - Signal handling - signal/xcpu,  Prev: Unit posix - Signal handling - signal/tstp,  Up: Unit posix - Signal handling

28.13.28 signal/pipe
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/xcpu,  Next: Unit posix - Signal handling - signal/xfsz,  Prev: Unit posix - Signal handling - signal/pipe,  Up: Unit posix - Signal handling

28.13.29 signal/xcpu
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/xfsz,  Next: Unit posix - Signal handling - signal/usr1,  Prev: Unit posix - Signal handling - signal/xcpu,  Up: Unit posix - Signal handling

28.13.30 signal/xfsz
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/usr1,  Next: Unit posix - Signal handling - signal/usr2,  Prev: Unit posix - Signal handling - signal/xfsz,  Up: Unit posix - Signal handling

28.13.31 signal/usr1
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/usr2,  Next: Unit posix - Signal handling - signal/winch,  Prev: Unit posix - Signal handling - signal/usr1,  Up: Unit posix - Signal handling

28.13.32 signal/usr2
--------------------


File: chicken.info,  Node: Unit posix - Signal handling - signal/winch,  Prev: Unit posix - Signal handling - signal/usr2,  Up: Unit posix - Signal handling

28.13.33 signal/winch
---------------------

These variables contain signal codes for use with `process-signal',
`set-signal-handler!',  `signal-handler',  `signal-masked?',
`signal-mask!',  or `signal-unmask!'.


File: chicken.info,  Node: Unit posix - Environment access,  Next: Unit posix - Memory mapped I/O,  Prev: Unit posix - Signal handling,  Up: Unit posix

28.14 Environment access
========================

* Menu:

* Unit posix - Environment access - current-environment::
* Unit posix - Environment access - setenv::
* Unit posix - Environment access - unsetenv::


File: chicken.info,  Node: Unit posix - Environment access - current-environment,  Next: Unit posix - Environment access - setenv,  Up: Unit posix - Environment access

28.14.1 current-environment
---------------------------


[procedure] (current-environment)
 Returns a association list of the environment variables and their
current values.


File: chicken.info,  Node: Unit posix - Environment access - setenv,  Next: Unit posix - Environment access - unsetenv,  Prev: Unit posix - Environment access - current-environment,  Up: Unit posix - Environment access

28.14.2 setenv
--------------


[procedure] (setenv VARIABLE VALUE)
 Sets the environment variable named `VARIABLE' to `VALUE'. Both
arguments should be strings. If the variable is not defined in the
environment, a new definition is created.


File: chicken.info,  Node: Unit posix - Environment access - unsetenv,  Prev: Unit posix - Environment access - setenv,  Up: Unit posix - Environment access

28.14.3 unsetenv
----------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Memory mapped I/O,  Next: Unit posix - Date and time routines,  Prev: Unit posix - Environment access,  Up: Unit posix

28.15 Memory mapped I/O
=======================

* Menu:

* Unit posix - Memory mapped I/O - memory-mapped-file?::
* Unit posix - Memory mapped I/O - map-file-to-memory::
* Unit posix - Memory mapped I/O - memory-mapped-file-pointer::
* Unit posix - Memory mapped I/O - unmap-file-from-memory::


File: chicken.info,  Node: Unit posix - Memory mapped I/O - memory-mapped-file?,  Next: Unit posix - Memory mapped I/O - map-file-to-memory,  Up: Unit posix - Memory mapped I/O

28.15.1 memory-mapped-file?
---------------------------


[pocedure] (memory-mapped-file? X)
 Returns `#t', if `X' is an object representing a memory mapped file,
or `#f' otherwise.


File: chicken.info,  Node: Unit posix - Memory mapped I/O - map-file-to-memory,  Next: Unit posix - Memory mapped I/O - memory-mapped-file-pointer,  Prev: Unit posix - Memory mapped I/O - memory-mapped-file?,  Up: Unit posix - Memory mapped I/O

28.15.2 map-file-to-memory
--------------------------


[procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
 Maps a section of a file to memory using the C function `mmap()'.
`ADDRESS' should be a foreign pointer object or `#f'; `LEN' specifies
the size of the section to be mapped; `PROTECTION' should be one or
more of the flags `prot/read, prot/write, prot/exec' or `prot/none'
bitwise-iored together; `FLAG' should be one or more of the flags
`map/fixed, map/shared, map/private, map/anonymous' or `map/file';
`FILENO' should be the file-descriptor of the mapped file. The optional
argument `OFFSET' gives the offset of the section of the file to be
mapped and defaults to 0. This procedure returns an object representing
the mapped file section.  The procedure `move-memory!' can be used to
access the mapped memory.


File: chicken.info,  Node: Unit posix - Memory mapped I/O - memory-mapped-file-pointer,  Next: Unit posix - Memory mapped I/O - unmap-file-from-memory,  Prev: Unit posix - Memory mapped I/O - map-file-to-memory,  Up: Unit posix - Memory mapped I/O

28.15.3 memory-mapped-file-pointer
----------------------------------


[procedure] (memory-mapped-file-pointer MMAP)
 Returns a machine pointer to the start of the memory region to which
the file is mapped.


File: chicken.info,  Node: Unit posix - Memory mapped I/O - unmap-file-from-memory,  Prev: Unit posix - Memory mapped I/O - memory-mapped-file-pointer,  Up: Unit posix - Memory mapped I/O

28.15.4 unmap-file-from-memory
------------------------------


[procedure] (unmap-file-from-memory MMAP [LEN])
 Unmaps the section of a file mapped to memory using the C function
`munmap()'.  `MMAP' should be a mapped file as returned by the
procedure `map-file-to-memory'.  The optional argument `LEN' specifies
the length of the section to be unmapped and defaults to the complete
length given when the file was mapped.


File: chicken.info,  Node: Unit posix - Date and time routines,  Next: Unit posix - Raw exit,  Prev: Unit posix - Memory mapped I/O,  Up: Unit posix

28.16 Date and time routines
============================

* Menu:

* Unit posix - Date and time routines - seconds->local-time::
* Unit posix - Date and time routines - local-time->seconds::
* Unit posix - Date and time routines - local-timezone-abbreviation::
* Unit posix - Date and time routines - seconds->string::
* Unit posix - Date and time routines - seconds->utc-time::
* Unit posix - Date and time routines - utc-time->seconds::
* Unit posix - Date and time routines - time->string::


File: chicken.info,  Node: Unit posix - Date and time routines - seconds->local-time,  Next: Unit posix - Date and time routines - local-time->seconds,  Up: Unit posix - Date and time routines

28.16.1 seconds->local-time
---------------------------


[procedure] (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 (0)
     the number of seconds after the minute (0 - 59)

minutes (1)
     the number of minutes after the hour (0 - 59)

hours (2)
     the number of hours past midnight (0 - 23)

mday (3)
     the day of the month (1 - 31)

month (4)
     the number of months since january (0 - 11)

year (5)
     the number of years since 1900

wday (6)
     the number of days since Sunday (0 - 6)

yday (7)
     the number of days since January 1 (0 - 365)

dstflag (8)
     a flag that is true if Daylight Saving Time is in effect at the
     time described.

timezone (9)
     the difference between UTC and the latest local standard time, in
     seconds west of UTC.



File: chicken.info,  Node: Unit posix - Date and time routines - local-time->seconds,  Next: Unit posix - Date and time routines - local-timezone-abbreviation,  Prev: Unit posix - Date and time routines - seconds->local-time,  Up: Unit posix - Date and time routines

28.16.2 local-time->seconds
---------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Date and time routines - local-timezone-abbreviation,  Next: Unit posix - Date and time routines - seconds->string,  Prev: Unit posix - Date and time routines - local-time->seconds,  Up: Unit posix - Date and time routines

28.16.3 local-timezone-abbreviation
-----------------------------------


[procedure] (local-timezone-abbreviation)
 Returns the abbreviation for the local timezone as a string.


File: chicken.info,  Node: Unit posix - Date and time routines - seconds->string,  Next: Unit posix - Date and time routines - seconds->utc-time,  Prev: Unit posix - Date and time routines - local-timezone-abbreviation,  Up: Unit posix - Date and time routines

28.16.4 seconds->string
-----------------------


[procedure] (seconds->string SECONDS)
 Converts the local time represented in `SECONDS' into a string of the
form `"Tue May 21 13:46:22 1991"'.


File: chicken.info,  Node: Unit posix - Date and time routines - seconds->utc-time,  Next: Unit posix - Date and time routines - utc-time->seconds,  Prev: Unit posix - Date and time routines - seconds->string,  Up: Unit posix - Date and time routines

28.16.5 seconds->utc-time
-------------------------


[procedure] (seconds->utc-time SECONDS)
 Similar to `seconds->local-time', but interpretes `SECONDS' as UTC
time.


File: chicken.info,  Node: Unit posix - Date and time routines - utc-time->seconds,  Next: Unit posix - Date and time routines - time->string,  Prev: Unit posix - Date and time routines - seconds->utc-time,  Up: Unit posix - Date and time routines

28.16.6 utc-time->seconds
-------------------------


[procedure] (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.


File: chicken.info,  Node: Unit posix - Date and time routines - time->string,  Prev: Unit posix - Date and time routines - utc-time->seconds,  Up: Unit posix - Date and time routines

28.16.7 time->string
--------------------


[procedure] (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"'.


File: chicken.info,  Node: Unit posix - Raw exit,  Next: Unit posix - ERRNO values,  Prev: Unit posix - Date and time routines,  Up: Unit posix

28.17 Raw exit
==============

* Menu:

* Unit posix - Raw exit - _exit::


File: chicken.info,  Node: Unit posix - Raw exit - _exit,  Up: Unit posix - Raw exit

28.17.1 _exit
-------------


[procedure] (_exit [CODE])
 Exits the current process without flushing any buffered output (using
the C function `_exit').  Note that the `exit-handler' is not called
when this procedure is invoked. The optional return-code `CODE'
defaults to `0'.


File: chicken.info,  Node: Unit posix - ERRNO values,  Next: Unit posix - Finding files,  Prev: Unit posix - Raw exit,  Up: Unit posix

28.18 ERRNO values
==================

* Menu:

* Unit posix - ERRNO values - errno/perm::
* Unit posix - ERRNO values - errno/noent::
* Unit posix - ERRNO values - errno/srch::
* Unit posix - ERRNO values - errno/intr::
* Unit posix - ERRNO values - errno/io::
* Unit posix - ERRNO values - errno/noexec::
* Unit posix - ERRNO values - errno/badf::
* Unit posix - ERRNO values - errno/child::
* Unit posix - ERRNO values - errno/nomem::
* Unit posix - ERRNO values - errno/acces::
* Unit posix - ERRNO values - errno/fault::
* Unit posix - ERRNO values - errno/busy::
* Unit posix - ERRNO values - errno/notdir::
* Unit posix - ERRNO values - errno/isdir::
* Unit posix - ERRNO values - errno/inval::
* Unit posix - ERRNO values - errno/mfile::
* Unit posix - ERRNO values - errno/nospc::
* Unit posix - ERRNO values - errno/spipe::
* Unit posix - ERRNO values - errno/pipe::
* Unit posix - ERRNO values - errno/again::
* Unit posix - ERRNO values - errno/rofs::
* Unit posix - ERRNO values - errno/exist::
* Unit posix - ERRNO values - errno/wouldblock::


File: chicken.info,  Node: Unit posix - ERRNO values - errno/perm,  Next: Unit posix - ERRNO values - errno/noent,  Up: Unit posix - ERRNO values

28.18.1 errno/perm
------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/noent,  Next: Unit posix - ERRNO values - errno/srch,  Prev: Unit posix - ERRNO values - errno/perm,  Up: Unit posix - ERRNO values

28.18.2 errno/noent
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/srch,  Next: Unit posix - ERRNO values - errno/intr,  Prev: Unit posix - ERRNO values - errno/noent,  Up: Unit posix - ERRNO values

28.18.3 errno/srch
------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/intr,  Next: Unit posix - ERRNO values - errno/io,  Prev: Unit posix - ERRNO values - errno/srch,  Up: Unit posix - ERRNO values

28.18.4 errno/intr
------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/io,  Next: Unit posix - ERRNO values - errno/noexec,  Prev: Unit posix - ERRNO values - errno/intr,  Up: Unit posix - ERRNO values

28.18.5 errno/io
----------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/noexec,  Next: Unit posix - ERRNO values - errno/badf,  Prev: Unit posix - ERRNO values - errno/io,  Up: Unit posix - ERRNO values

28.18.6 errno/noexec
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/badf,  Next: Unit posix - ERRNO values - errno/child,  Prev: Unit posix - ERRNO values - errno/noexec,  Up: Unit posix - ERRNO values

28.18.7 errno/badf
------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/child,  Next: Unit posix - ERRNO values - errno/nomem,  Prev: Unit posix - ERRNO values - errno/badf,  Up: Unit posix - ERRNO values

28.18.8 errno/child
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/nomem,  Next: Unit posix - ERRNO values - errno/acces,  Prev: Unit posix - ERRNO values - errno/child,  Up: Unit posix - ERRNO values

28.18.9 errno/nomem
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/acces,  Next: Unit posix - ERRNO values - errno/fault,  Prev: Unit posix - ERRNO values - errno/nomem,  Up: Unit posix - ERRNO values

28.18.10 errno/acces
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/fault,  Next: Unit posix - ERRNO values - errno/busy,  Prev: Unit posix - ERRNO values - errno/acces,  Up: Unit posix - ERRNO values

28.18.11 errno/fault
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/busy,  Next: Unit posix - ERRNO values - errno/notdir,  Prev: Unit posix - ERRNO values - errno/fault,  Up: Unit posix - ERRNO values

28.18.12 errno/busy
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/notdir,  Next: Unit posix - ERRNO values - errno/isdir,  Prev: Unit posix - ERRNO values - errno/busy,  Up: Unit posix - ERRNO values

28.18.13 errno/notdir
---------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/isdir,  Next: Unit posix - ERRNO values - errno/inval,  Prev: Unit posix - ERRNO values - errno/notdir,  Up: Unit posix - ERRNO values

28.18.14 errno/isdir
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/inval,  Next: Unit posix - ERRNO values - errno/mfile,  Prev: Unit posix - ERRNO values - errno/isdir,  Up: Unit posix - ERRNO values

28.18.15 errno/inval
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/mfile,  Next: Unit posix - ERRNO values - errno/nospc,  Prev: Unit posix - ERRNO values - errno/inval,  Up: Unit posix - ERRNO values

28.18.16 errno/mfile
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/nospc,  Next: Unit posix - ERRNO values - errno/spipe,  Prev: Unit posix - ERRNO values - errno/mfile,  Up: Unit posix - ERRNO values

28.18.17 errno/nospc
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/spipe,  Next: Unit posix - ERRNO values - errno/pipe,  Prev: Unit posix - ERRNO values - errno/nospc,  Up: Unit posix - ERRNO values

28.18.18 errno/spipe
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/pipe,  Next: Unit posix - ERRNO values - errno/again,  Prev: Unit posix - ERRNO values - errno/spipe,  Up: Unit posix - ERRNO values

28.18.19 errno/pipe
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/again,  Next: Unit posix - ERRNO values - errno/rofs,  Prev: Unit posix - ERRNO values - errno/pipe,  Up: Unit posix - ERRNO values

28.18.20 errno/again
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/rofs,  Next: Unit posix - ERRNO values - errno/exist,  Prev: Unit posix - ERRNO values - errno/again,  Up: Unit posix - ERRNO values

28.18.21 errno/rofs
-------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/exist,  Next: Unit posix - ERRNO values - errno/wouldblock,  Prev: Unit posix - ERRNO values - errno/rofs,  Up: Unit posix - ERRNO values

28.18.22 errno/exist
--------------------


File: chicken.info,  Node: Unit posix - ERRNO values - errno/wouldblock,  Prev: Unit posix - ERRNO values - errno/exist,  Up: Unit posix - ERRNO values

28.18.23 errno/wouldblock
-------------------------

These variables contain error codes as returned by `errno'.


File: chicken.info,  Node: Unit posix - Finding files,  Next: Unit posix - Getting the hostname and system information,  Prev: Unit posix - ERRNO values,  Up: Unit posix

28.19 Finding files
===================

* Menu:

* Unit posix - Finding files - find-files::


File: chicken.info,  Node: Unit posix - Finding files - find-files,  Up: Unit posix - Finding files

28.19.1 find-files
------------------


[procedure] (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 in 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 be 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. For example, a
depth of `0' means that only files in the top-level, specified
directory are to be traversed. In this case, all nested directories are
ignored.  `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.


File: chicken.info,  Node: Unit posix - Getting the hostname and system information,  Next: Unit posix - Setting the file buffering mode,  Prev: Unit posix - Finding files,  Up: Unit posix

28.20 Getting the hostname and system information
=================================================

* Menu:

* Unit posix - Getting the hostname and system information - get-host-name::
* Unit posix - Getting the hostname and system information - system-information::


File: chicken.info,  Node: Unit posix - Getting the hostname and system information - get-host-name,  Next: Unit posix - Getting the hostname and system information - system-information,  Up: Unit posix - Getting the hostname and system information

28.20.1 get-host-name
---------------------


[procedure] (get-host-name)
 Returns the hostname of the machine that this process is running on.


File: chicken.info,  Node: Unit posix - Getting the hostname and system information - system-information,  Prev: Unit posix - Getting the hostname and system information - get-host-name,  Up: Unit posix - Getting the hostname and system information

28.20.2 system-information
--------------------------


[procedure] (system-information)
 Invokes the UNIX system call `uname()' and returns a list of 5 values:
system-name, node-name, OS release, OS version and machine.


File: chicken.info,  Node: Unit posix - Setting the file buffering mode,  Next: Unit posix - Terminal ports,  Prev: Unit posix - Getting the hostname and system information,  Up: Unit posix

28.21 Setting the file buffering mode
=====================================

* Menu:

* Unit posix - Setting the file buffering mode - set-buffering-mode!::


File: chicken.info,  Node: Unit posix - Setting the file buffering mode - set-buffering-mode!,  Up: Unit posix - Setting the file buffering mode

28.21.1 set-buffering-mode!
---------------------------


[procedure] (set-buffering-mode! PORT MODE [BUFSIZE])
 Sets the buffering-mode for the file associated with `PORT' to `MODE',
which should be one of the keywords `#:full', `#:line' or `#:none'. If
`BUFSIZE' is specified it determines the size of the buffer to be used
(if any).


File: chicken.info,  Node: Unit posix - Terminal ports,  Next: Unit posix - How Scheme procedures relate to UNIX C functions,  Prev: Unit posix - Setting the file buffering mode,  Up: Unit posix

28.22 Terminal ports
====================

* Menu:

* Unit posix - Terminal ports - terminal-name::
* Unit posix - Terminal ports - terminal-port?::


File: chicken.info,  Node: Unit posix - Terminal ports - terminal-name,  Next: Unit posix - Terminal ports - terminal-port?,  Up: Unit posix - Terminal ports

28.22.1 terminal-name
---------------------


[procedure] (terminal-name PORT)
 Returns the name of the terminal that is connected to `PORT'.


File: chicken.info,  Node: Unit posix - Terminal ports - terminal-port?,  Prev: Unit posix - Terminal ports - terminal-name,  Up: Unit posix - Terminal ports

28.22.2 terminal-port?
----------------------


[procedure] (terminal-port? PORT)
 Returns `#t' if `PORT' is connected to a terminal and `#f' otherwise.


File: chicken.info,  Node: Unit posix - How Scheme procedures relate to UNIX C functions,  Next: Unit posix - Windows specific notes,  Prev: Unit posix - Terminal ports,  Up: Unit posix

28.23 How Scheme procedures relate to UNIX C functions
======================================================

`change-directory'
     `chdir'

`change-file-mode'
     `chmod'

`change-file-owner'
     `chown'

`create-directory'
     `mkdir'

`create-fifo'
     `mkfifo'

`create-pipe'
     `pipe'

`create-session'
     `setsid'

`create-symbolic-link'
     `link'

`current-directory'
     `curdir'

`current-effective-groupd-id'
     `getegid'

`current-effective-user-id'
     `geteuid'

`current-group-id'
     `getgid'

`current-parent-id'
     `getppid'

`current-process-id'
     `getpid'

`current-user-id'
     `getuid'

`delete-directory'
     `rmdir'

`duplicate-fileno'
     `dup/dup2'

`_exit'
     `_exit'

`file-close'
     `close'

`file-access-time'
     `stat'

`file-change-time'
     `stat'

`file-modification-time'
     `stat'

`file-execute-access?'
     `access'

`file-open'
     `open'

`file-lock'
     `fcntl'

`file-position'
     `ftell/lseek'

`file-read'
     `read'

`file-read-access?'
     `access'

`file-select'
     `select'

`file-control'
     `fcntl'

`file-stat'
     `stat'

`file-test-lock'
     `fcntl'

`file-truncate'
     `truncate/ftruncate'

`file-unlock'
     `fcntl'

`file-write'
     `write'

`file-write-access?'
     `access'

`get-groups'
     `getgroups'

`get-host-name'
     `gethostname'

`initialize-groups'
     `initgroups'

`local-time->seconds'
     `mktime'

`local-timezone-abbreviation'
     `localtime'

`map-file-to-memory'
     `mmap'

`open-input-file*'
     `fdopen'

`open-output-file*'
     `fdopen'

`open-input-pipe'
     `popen'

`open-output-pipe'
     `popen'

`port->fileno'
     `fileno'

`process-execute'
     `execvp'

`process-fork'
     `fork'

`process-group-id'
     `getpgid'

`process-signal'
     `kill'

`process-wait'
     `waitpid'

`close-input-pipe'
     `pclose'

`close-output-pipe'
     `pclose'

`read-symbolic-link'
     `readlink'

`seconds->local-time'
     `localtime'

`seconds->string'
     `ctime'

`seconds->utc-time'
     `gmtime'

`set-alarm!'
     `alarm'

`set-buffering-mode!'
     `setvbuf'

`set-file-position!'
     `fseek/seek'

`set-groups!'
     `setgroups'

`set-signal-mask!'
     `sigprocmask'

`set-group-id!'
     `setgid'

`set-process-group-id!'
     `setpgid'

`set-user-id!'
     `setuid'

`set-root-directory!'
     `chroot'

`setenv'
     `setenv/putenv'

`sleep'
     `sleep'

`system-information'
     `uname'

`terminal-name'
     `ttyname'

`terminal-port?'
     `isatty'

`time->string'
     `asctime'

`unsetenv'
     `putenv'

`unmap-file-from-memory'
     `munmap'

`user-information'
     `getpwnam/getpwuid'

`utc-time->seconds'
     `timegm'



File: chicken.info,  Node: Unit posix - Windows specific notes,  Prev: Unit posix - How Scheme procedures relate to UNIX C functions,  Up: Unit posix

28.24 Windows specific notes
============================

* Menu:

* Unit posix - Windows specific notes - Procedure Changes::
* Unit posix - Windows specific notes - Unsupported Definitions::
* Unit posix - Windows specific notes - Additional Definitions::
* Unit posix - Windows specific notes - process-spawn::

   Use of UTF8 encoded strings is for pathnames is not supported.
Windows uses a 16-bit UNICODE encoding with special system calls for
wide-character support. Only single-byte string encoding can be used.


File: chicken.info,  Node: Unit posix - Windows specific notes - Procedure Changes,  Next: Unit posix - Windows specific notes - Unsupported Definitions,  Up: Unit posix - Windows specific notes

28.24.1 Procedure Changes
-------------------------

Exceptions to the above procedure definitions.


[procedure] (create-pipe [MODE])
 The optional parameter `MODE', default `open/binary | open/noinherit'.
This can be `open/binary' or `open/text', optionally or'ed with
`open/noinherit'.


[procedure] (process-wait [PID [NOHANG]])
 `process-wait' always returns `#t' for a terminated process and only
the exit status is available. (Windows does not provide signals as an
interprocess communication method.)


[procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
[procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
[procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
 The optional parameter `EXACT-FLAG', default `#f'. When `#f' any
argument string with embedded whitespace will be wrapped in quotes.
When `#t' no such wrapping occurs.


File: chicken.info,  Node: Unit posix - Windows specific notes - Unsupported Definitions,  Next: Unit posix - Windows specific notes - Additional Definitions,  Prev: Unit posix - Windows specific notes - Procedure Changes,  Up: Unit posix - Windows specific notes

28.24.2 Unsupported Definitions
-------------------------------

The following definitions are not supported for native Windows builds
(compiled with the Microsoft tools or with MinGW):


open/noctty  open/nonblock  open/fsync  open/sync
perm/isvtx  perm/isuid  perm/isgid
file-select file-control
signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
user-information  group-information  get-groups  set-groups!  initialize-groups
errno/wouldblock
change-file-owner
current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
set-user-id!  set-group-id!
create-session
process-group-id  set-process-group-id!
create-symbolic-link  read-symbolic-link
file-truncate
file-lock  file-lock/blocking  file-unlock  file-test-lock
create-fifo  fifo?
prot/...
map/...
map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
set-alarm!
terminal-port?  terminal-name
process-fork  process-signal
parent-process-id
set-root-directory!
utc-time->seconds


File: chicken.info,  Node: Unit posix - Windows specific notes - Additional Definitions,  Next: Unit posix - Windows specific notes - process-spawn,  Prev: Unit posix - Windows specific notes - Unsupported Definitions,  Up: Unit posix - Windows specific notes

28.24.3 Additional Definitions
------------------------------

Only available for Windows

   * open/noinherit

   This variable is a mode value for `create-pipe'. Useful when
spawning a child process.

   * spawn/overlay

   * spawn/wait

   * spawn/nowait

   * spawn/nowaito

   * spawn/detach

   These variables contains special flags that specify the exact
semantics of `process-spawn': `spawn/overlay' replaces the current
process with the new one. `spawn/wait' suspends execution of the
current process until the spawned process returns. `spawn/nowait' does
the opposite (`spawn/nowaito' is identical, according to the Microsoft
documentation) and runs the process asynchronously. `spawn/detach' runs
the new process in the background, without being attached to a console.


File: chicken.info,  Node: Unit posix - Windows specific notes - process-spawn,  Prev: Unit posix - Windows specific notes - Additional Definitions,  Up: Unit posix - Windows specific notes

28.24.4 process-spawn
---------------------


[procedure] (process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
 Creates and runs a new process with the given `COMMAND' filename and
the optional `ARGUMENT-LIST' and `ENVIRONMENT-LIST'. `MODE' specifies
how exactly the process should be executed and must be one or more of
the `spawn/...' flags defined above.

The `EXACT-FLAG', default `#f', controls quote-wrapping of argument
strings. When `#t' quote-wrapping is not performed.

   Returns:

   * the exit status when synchronous

   * the PID when asynchronous

   * -1 when failure

   Previous: *Note Unit srfi-18: Unit srfi-18.

   Next: *Note Unit utils: Unit utils.


File: chicken.info,  Node: Unit utils,  Next: Unit tcp,  Prev: Unit posix,  Up: Top

29 Unit utils
*************

* Menu:

* Unit utils - Environment Query::
* Unit utils - Iterating over input lines and files::
* Unit utils - Executing shell commands with formatstring and error checking::
* Unit utils - Reading a file's contents::

   This unit contains apropos and functions as a "grab bag" of
procedures without a good home, and which don't have to be available by
default (as compared to the *Note extras: Unit extras. unit).

   This unit uses the `extras' and `regex' units.


File: chicken.info,  Node: Unit utils - Environment Query,  Next: Unit utils - Iterating over input lines and files,  Up: Unit utils

29.1 Environment Query
======================

* Menu:

* Unit utils - Environment Query - apropos::
* Unit utils - Environment Query - apropos-list::


File: chicken.info,  Node: Unit utils - Environment Query - apropos,  Next: Unit utils - Environment Query - apropos-list,  Up: Unit utils - Environment Query

29.1.1 apropos
--------------


[procedure] (apropos SYMBOL-PATTERN [ENVIRONMENT] [#:MACROS?])
 Displays symbols & type matching `SYMBOL-PATTERN' in the `ENVIRONMENT'
on the `(current-output-port)'.

`SYMBOL-PATTERN'
     A symbol, string, or regex. When symbol or string substring
     matching is performed.

`ENVIRONMENT'
     An environment. When missing the `(interaction-environment)' is
     assumed.

`#:MACROS?'
     Keyword argument. A boolean. Include macro symbols? When missing
     `#f' is assumed.



File: chicken.info,  Node: Unit utils - Environment Query - apropos-list,  Prev: Unit utils - Environment Query - apropos,  Up: Unit utils - Environment Query

29.1.2 apropos-list
-------------------


[procedure] (apropos-list SYMBOL-PATTERN [ENVIRONMENT] [#:MACROS?])
 Like `apropos' but returns a list of matching symbols.


File: chicken.info,  Node: Unit utils - Iterating over input lines and files,  Next: Unit utils - Executing shell commands with formatstring and error checking,  Prev: Unit utils - Environment Query,  Up: Unit utils

29.2 Iterating over input lines and files
=========================================

* Menu:

* Unit utils - Iterating over input lines and files - for-each-line::
* Unit utils - Iterating over input lines and files - for-each-argv-line::


File: chicken.info,  Node: Unit utils - Iterating over input lines and files - for-each-line,  Next: Unit utils - Iterating over input lines and files - for-each-argv-line,  Up: Unit utils - Iterating over input lines and files

29.2.1 for-each-line
--------------------


[procedure] (for-each-line PROCEDURE [PORT])
 Calls `PROCEDURE' for each line read from `PORT' (which defaults to
the value of `(current-input-port)'. The argument passed to `PROCEDURE'
is a string with the contents of the line, excluding any
line-terminators. When all input has been read from the port,
`for-each-line' returns some unspecified value.


File: chicken.info,  Node: Unit utils - Iterating over input lines and files - for-each-argv-line,  Prev: Unit utils - Iterating over input lines and files - for-each-line,  Up: Unit utils - Iterating over input lines and files

29.2.2 for-each-argv-line
-------------------------


[procedure] (for-each-argv-line PROCEDURE)
 Opens each file listed on the command line in order, passing one line
at a time into `PROCEDURE'.  The filename `-' is interpreted as
`(current-input-port)'.  If no arguments are given on the command line
it again uses the value of `(current-input-port)'. During execution of
`PROCEDURE', the current input port will be correctly bound to the
current input source.

This code will act as a simple Unix cat(1) command:

     (for-each-argv-line print)


File: chicken.info,  Node: Unit utils - Executing shell commands with formatstring and error checking,  Next: Unit utils - Reading a file's contents,  Prev: Unit utils - Iterating over input lines and files,  Up: Unit utils

29.3 Executing shell commands with formatstring and error checking
==================================================================

* Menu:

* Unit utils - Executing shell commands with formatstring and error checking - system*::


File: chicken.info,  Node: Unit utils - Executing shell commands with formatstring and error checking - system*,  Up: Unit utils - Executing shell commands with formatstring and error checking

29.3.1 system*
--------------


[procedure] (system* FORMATSTRING ARGUMENT1 ...)
 Similar to `(system (sprintf FORMATSTRING ARGUMENT1 ...))', but
signals an error if the invoked program should return a nonzero exit
status.


File: chicken.info,  Node: Unit utils - Reading a file's contents,  Prev: Unit utils - Executing shell commands with formatstring and error checking,  Up: Unit utils

29.4 Reading a file's contents
==============================

* Menu:

* Unit utils - Reading a file's contents - read-all::


File: chicken.info,  Node: Unit utils - Reading a file's contents - read-all,  Up: Unit utils - Reading a file's contents

29.4.1 read-all
---------------


[procedure] (read-all [FILE-OR-PORT])
 If `FILE-OR-PORT' is a string, then this procedure returns the
contents of the file as a string. If `FILE-OR-PORT' is a port, all
remaining input is read and returned as a string. The port is not
closed. If no argument is provided, input will be read from the port
that is the current value of `(current-input-port)'.

Previous: *Note Unit posix: Unit posix.

   Next: *Note Unit tcp: Unit tcp.


File: chicken.info,  Node: Unit tcp,  Next: Unit lolevel,  Prev: Unit utils,  Up: Top

30 Unit tcp
***********

* Menu:

* Unit tcp - tcp-listen::
* Unit tcp - tcp-listener?::
* Unit tcp - tcp-close::
* Unit tcp - tcp-accept::
* Unit tcp - tcp-accept-ready?::
* Unit tcp - tcp-listener-port::
* Unit tcp - tcp-listener-fileno::
* Unit tcp - tcp-connect::
* Unit tcp - tcp-addresses::
* Unit tcp - tcp-port-numbers::
* Unit tcp - tcp-abandon-port::
* Unit tcp - tcp-buffer-size::
* Unit tcp - tcp-read-timeout::
* Unit tcp - tcp-write-timeout::
* Unit tcp - tcp-connect-timeout::
* Unit tcp - tcp-accept-timeout::
* Unit tcp - Example::

   This unit provides basic facilities for communicating over TCP
sockets. The socket interface should be mostly compatible to the one
found in PLT Scheme.

   This unit uses the `extras' unit.

   All errors related to failing network operations will raise a
condition of kind `(exn i/o network)'.


File: chicken.info,  Node: Unit tcp - tcp-listen,  Next: Unit tcp - tcp-listener?,  Up: Unit tcp

30.1 tcp-listen
===============


[procedure] (tcp-listen TCPPORT [BACKLOG [HOST]])
 Creates and returns a TCP listener object that listens for connections
on `TCPPORT', which should be an exact integer. `BACKLOG' specifies the
number of maximally pending connections (and defaults to 4). If the
optional argument `HOST' is given and not `#f', then only incoming
connections for the given host (or IP) are accepted.


File: chicken.info,  Node: Unit tcp - tcp-listener?,  Next: Unit tcp - tcp-close,  Prev: Unit tcp - tcp-listen,  Up: Unit tcp

30.2 tcp-listener?
==================


[procedure] (tcp-listener? X)
 Returns `#t' if `X' is a TCP listener object, or `#f' otherwise.


File: chicken.info,  Node: Unit tcp - tcp-close,  Next: Unit tcp - tcp-accept,  Prev: Unit tcp - tcp-listener?,  Up: Unit tcp

30.3 tcp-close
==============


[procedure] (tcp-close LISTENER)
 Reclaims any resources associated with `LISTENER'.


File: chicken.info,  Node: Unit tcp - tcp-accept,  Next: Unit tcp - tcp-accept-ready?,  Prev: Unit tcp - tcp-close,  Up: Unit tcp

30.4 tcp-accept
===============


[procedure] (tcp-accept LISTENER)
 Waits until a connection is established on the port on which
`LISTENER' is listening and returns two values: an input- and
output-port that can be used to communicate with the remote process.
The current value of `tcp-accept-timeout' is used to determine the
maximal number of milliseconds (if any) to wait until a connection is
established. When a client connects any  read- and write-operations on
the returned ports will use the current values (at the time of the
connection) of `tcp-read-timeout' and `tcp-write-timeout',
respectively, to determine the maximal number of milliseconds to wait
for input/output before a timeout error is signalled.

Note: this operation and any I/O on the ports returned will not block
other running threads.


File: chicken.info,  Node: Unit tcp - tcp-accept-ready?,  Next: Unit tcp - tcp-listener-port,  Prev: Unit tcp - tcp-accept,  Up: Unit tcp

30.5 tcp-accept-ready?
======================


[procedure] (tcp-accept-ready? LISTENER)
 Returns `#t' if there are any connections pending on `LISTENER', or
`#f' otherwise.


File: chicken.info,  Node: Unit tcp - tcp-listener-port,  Next: Unit tcp - tcp-listener-fileno,  Prev: Unit tcp - tcp-accept-ready?,  Up: Unit tcp

30.6 tcp-listener-port
======================


[procedure] (tcp-listener-port LISTENER)
 Returns the port number assigned to `LISTENER' (If you pass `0' to
`tcp-listen', then the system will choose a port-number for you).


File: chicken.info,  Node: Unit tcp - tcp-listener-fileno,  Next: Unit tcp - tcp-connect,  Prev: Unit tcp - tcp-listener-port,  Up: Unit tcp

30.7 tcp-listener-fileno
========================


[procedure] (tcp-listener-fileno LISTENER)
 Returns the file-descriptor associated with `LISTENER'.


File: chicken.info,  Node: Unit tcp - tcp-connect,  Next: Unit tcp - tcp-addresses,  Prev: Unit tcp - tcp-listener-fileno,  Up: Unit tcp

30.8 tcp-connect
================


[procedure] (tcp-connect HOSTNAME [TCPPORT])
 Establishes a client-side TCP connection to the machine with the name
`HOSTNAME' (a string) at `TCPPORT' (an exact integer) and returns two
values: an input- and output-port for communicating with the remote
process. The current value of `tcp-connect-timeout' is used to
determine the maximal number of milliseconds (if any) to wait until the
connection is established. When the connection takes place any read-
and write-operations on the returned ports will use the current values
(at the time of the call to `tcp-connect') of `tcp-read-timeout' and
`tcp-write-timeout', respectively, to determine the maximal number of
milliseconds to wait for input/output before a timeout error is
signalled.

If the `TCPPORT' is omitted, the port is parsed from the `HOSTNAME'
string.  The format expected is `HOSTNAME:PORT'.  The `PORT' can either
be a string representation of an integer or a service name which is
translated to an integer using the POSIX function `getservbyname'
(http://www.opengroup.org/onlinepubs/009695399/functions/getservbyname.html).

   Note: any I/O on the ports returned will not block other running
threads.


File: chicken.info,  Node: Unit tcp - tcp-addresses,  Next: Unit tcp - tcp-port-numbers,  Prev: Unit tcp - tcp-connect,  Up: Unit tcp

30.9 tcp-addresses
==================


[procedure] (tcp-addresses PORT)
 Returns two values for the input- or output-port `PORT' (which should
be a port returned by either `tcp-accept' or `tcp-connect'): the IP
address of the local and the remote machine that are connected over the
socket associated with `PORT'. The returned addresses are strings in
`XXX.XXX.XXX.XXX' notation.


File: chicken.info,  Node: Unit tcp - tcp-port-numbers,  Next: Unit tcp - tcp-abandon-port,  Prev: Unit tcp - tcp-addresses,  Up: Unit tcp

30.10 tcp-port-numbers
======================


[procedure] (tcp-port-numbers PORT)
 Returns two values for the input- or output-port `PORT' (which should
be a port returned by either `tcp-accept' or `tcp-connect'): the TCP
port numbers of the local and the remote machine that are connected
over the socket associated with `PORT'.


File: chicken.info,  Node: Unit tcp - tcp-abandon-port,  Next: Unit tcp - tcp-buffer-size,  Prev: Unit tcp - tcp-port-numbers,  Up: Unit tcp

30.11 tcp-abandon-port
======================


[procedure] (tcp-abandon-port PORT)
 Marks the socket port `PORT' as abandoned. This is mainly useful to
close down a port without breaking the connection.


File: chicken.info,  Node: Unit tcp - tcp-buffer-size,  Next: Unit tcp - tcp-read-timeout,  Prev: Unit tcp - tcp-abandon-port,  Up: Unit tcp

30.12 tcp-buffer-size
=====================


[parameter] tcp-buffer-size
 Sets the size of the output buffer. By default no output-buffering for
TCP output is done, but to improve performance by minimizing the number
of TCP packets, buffering may be turned on by setting this parameter to
an exact integer greater zero. A buffer size of zero or `#f' turns
buffering off. The setting of this parameter takes effect at the time
when the I/O ports for a particular socket are created, i.e. when
`tcp-connect' or `tcp-accept' is called.

Note that since output is not immediately written to the associated
socket, you may need to call `flush-output', once you want the output
to be transmitted. Closing the output port will flush automatically.


File: chicken.info,  Node: Unit tcp - tcp-read-timeout,  Next: Unit tcp - tcp-write-timeout,  Prev: Unit tcp - tcp-buffer-size,  Up: Unit tcp

30.13 tcp-read-timeout
======================


[parameter] tcp-read-timeout
 Determines the timeout for TCP read operations in milliseconds. A
timeout of `#f' disables timeout checking. The default read timeout is
60000, i.e. 1 minute.


File: chicken.info,  Node: Unit tcp - tcp-write-timeout,  Next: Unit tcp - tcp-connect-timeout,  Prev: Unit tcp - tcp-read-timeout,  Up: Unit tcp

30.14 tcp-write-timeout
=======================


[parameter] tcp-write-timeout
 Determines the timeout for TCP write operations in milliseconds. A
timeout of `#f' disables timeout checking. The default write timeout is
60000, i.e. 1 minute.


File: chicken.info,  Node: Unit tcp - tcp-connect-timeout,  Next: Unit tcp - tcp-accept-timeout,  Prev: Unit tcp - tcp-write-timeout,  Up: Unit tcp

30.15 tcp-connect-timeout
=========================


[parameter] tcp-connect-timeout
 Determines the timeout for `tcp-connect' operations in milliseconds. A
timeout of `#f' disables timeout checking and is the default.


File: chicken.info,  Node: Unit tcp - tcp-accept-timeout,  Next: Unit tcp - Example,  Prev: Unit tcp - tcp-connect-timeout,  Up: Unit tcp

30.16 tcp-accept-timeout
========================


[parameter] tcp-accept-timeout
 Determines the timeout for `tcp-accept' operations in milliseconds. A
timeout of `#f' disables timeout checking and is the default.


File: chicken.info,  Node: Unit tcp - Example,  Prev: Unit tcp - tcp-accept-timeout,  Up: Unit tcp

30.17 Example
=============

A very simple example follows. Say we have the two files `client.scm'
and `server.scm':

     _; client.scm
     _(declare (uses tcp))
     (define-values (i o) (tcp-connect *"localhost"* 4242))
     (write-line *"Good Bye!"* o)
     (print (read-line i))

     _; server.scm
     _(declare (uses tcp))
     (*define* *l* (tcp-listen 4242))
     (define-values (i o) (tcp-accept l))
     (write-line *"Hello!"* o)
     (print (read-line i))
     (close-input-port i)
     (close-output-port o)


% csc server.scm
% csc client.scm
% ./server &
% ./client
Good Bye!
Hello!
 Previous: *Note Unit utils: Unit utils.

   Next: *Note Unit lolevel: Unit lolevel.


File: chicken.info,  Node: Unit lolevel,  Next: Interface to external functions and variables,  Prev: Unit tcp,  Up: Top

31 Unit lolevel
***************

* Menu:

* Unit lolevel - Foreign pointers::
* Unit lolevel - Tagged pointers::
* Unit lolevel - Extending procedures with data::
* Unit lolevel - Data in unmanaged memory::
* Unit lolevel - Locatives::
* Unit lolevel - Accessing toplevel variables::
* Unit lolevel - Low-level data access::
* Unit lolevel - Procedure-call- and variable reference hooks::
* Unit lolevel - Magic::

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

   This unit uses the `srfi-4' and `extras' units.


File: chicken.info,  Node: Unit lolevel - Foreign pointers,  Next: Unit lolevel - Tagged pointers,  Up: Unit lolevel

31.1 Foreign pointers
=====================

* Menu:

* Unit lolevel - Foreign pointers - address->pointer::
* Unit lolevel - Foreign pointers - allocate::
* Unit lolevel - Foreign pointers - free::
* Unit lolevel - Foreign pointers - null-pointer::
* Unit lolevel - Foreign pointers - null-pointer?::
* Unit lolevel - Foreign pointers - object->pointer::
* Unit lolevel - Foreign pointers - pointer?::
* Unit lolevel - Foreign pointers - pointer=?::
* Unit lolevel - Foreign pointers - pointer->address::
* Unit lolevel - Foreign pointers - pointer->object::
* Unit lolevel - Foreign pointers - pointer-offset::
* Unit lolevel - Foreign pointers - pointer-u8-ref::
* Unit lolevel - Foreign pointers - pointer-s8-ref::
* Unit lolevel - Foreign pointers - pointer-u16-ref::
* Unit lolevel - Foreign pointers - pointer-s16-ref::
* Unit lolevel - Foreign pointers - pointer-u32-ref::
* Unit lolevel - Foreign pointers - pointer-s32-ref::
* Unit lolevel - Foreign pointers - pointer-f32-ref::
* Unit lolevel - Foreign pointers - pointer-f64-ref::
* Unit lolevel - Foreign pointers - pointer-u8-set!::
* Unit lolevel - Foreign pointers - pointer-s8-set!::
* Unit lolevel - Foreign pointers - pointer-u16-set!::
* Unit lolevel - Foreign pointers - pointer-s16-set!::
* Unit lolevel - Foreign pointers - pointer-u32-set!::
* Unit lolevel - Foreign pointers - pointer-s32-set!::
* Unit lolevel - Foreign pointers - pointer-f32-set!::
* Unit lolevel - Foreign pointers - pointer-f64-set!::
* Unit lolevel - Foreign pointers - align-to-word::


File: chicken.info,  Node: Unit lolevel - Foreign pointers - address->pointer,  Next: Unit lolevel - Foreign pointers - allocate,  Up: Unit lolevel - Foreign pointers

31.1.1 address->pointer
-----------------------


[procedure] (address->pointer ADDRESS)
 Creates a new foreign pointer object initialized to point to the
address given in the integer `ADDRESS'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - allocate,  Next: Unit lolevel - Foreign pointers - free,  Prev: Unit lolevel - Foreign pointers - address->pointer,  Up: Unit lolevel - Foreign pointers

31.1.2 allocate
---------------


[procedure] (allocate BYTES)
 Returns a pointer to a freshly allocated region of static memory. This
procedure could be defined as follows:

     (*define* *allocate* (foreign-lambda c-pointer *"malloc"* integer))


File: chicken.info,  Node: Unit lolevel - Foreign pointers - free,  Next: Unit lolevel - Foreign pointers - null-pointer,  Prev: Unit lolevel - Foreign pointers - allocate,  Up: Unit lolevel - Foreign pointers

31.1.3 free
-----------


[procedure] (free POINTER)
 Frees the memory pointed to by `POINTER'.  This procedure could be
defined as follows:

     (*define* *free* (foreign-lambda c-pointer *"free"* integer))


File: chicken.info,  Node: Unit lolevel - Foreign pointers - null-pointer,  Next: Unit lolevel - Foreign pointers - null-pointer?,  Prev: Unit lolevel - Foreign pointers - free,  Up: Unit lolevel - Foreign pointers

31.1.4 null-pointer
-------------------


[procedure] (null-pointer)
 Another way to say `(address->pointer 0)'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - null-pointer?,  Next: Unit lolevel - Foreign pointers - object->pointer,  Prev: Unit lolevel - Foreign pointers - null-pointer,  Up: Unit lolevel - Foreign pointers

31.1.5 null-pointer?
--------------------


[procedure] (null-pointer? PTR)
 Returns `#t' if `PTR' contains a `NULL' pointer, or `#f' otherwise.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - object->pointer,  Next: Unit lolevel - Foreign pointers - pointer?,  Prev: Unit lolevel - Foreign pointers - null-pointer?,  Up: Unit lolevel - Foreign pointers

31.1.6 object->pointer
----------------------


[procedure] (object->pointer X)
 Returns a pointer pointing to the Scheme object X, which should be a
non-immediate object.  Note that data in the garbage collected heap
moves during garbage collection.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer?,  Next: Unit lolevel - Foreign pointers - pointer=?,  Prev: Unit lolevel - Foreign pointers - object->pointer,  Up: Unit lolevel - Foreign pointers

31.1.7 pointer?
---------------


[procedure] (pointer? X)
 Returns `#t' if `X' is a foreign pointer object, and `#f' otherwise.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer=?,  Next: Unit lolevel - Foreign pointers - pointer->address,  Prev: Unit lolevel - Foreign pointers - pointer?,  Up: Unit lolevel - Foreign pointers

31.1.8 pointer=?
----------------


[procedure] (pointer=? PTR1 PTR2)
 Returns `#t' if the pointer-like objects `PTR1' and `PTR2' point to
the same address.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer->address,  Next: Unit lolevel - Foreign pointers - pointer->object,  Prev: Unit lolevel - Foreign pointers - pointer=?,  Up: Unit lolevel - Foreign pointers

31.1.9 pointer->address
-----------------------


[procedure] (pointer->address PTR)
 Returns the address, to which the pointer `PTR' points.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer->object,  Next: Unit lolevel - Foreign pointers - pointer-offset,  Prev: Unit lolevel - Foreign pointers - pointer->address,  Up: Unit lolevel - Foreign pointers

31.1.10 pointer->object
-----------------------


[procedure] (pointer->object PTR)
 Returns the Scheme object pointed to by the pointer `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-offset,  Next: Unit lolevel - Foreign pointers - pointer-u8-ref,  Prev: Unit lolevel - Foreign pointers - pointer->object,  Up: Unit lolevel - Foreign pointers

31.1.11 pointer-offset
----------------------


[procedure] (pointer-offset PTR N)
 Returns a new pointer representing the pointer `PTR' increased by `N'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u8-ref,  Next: Unit lolevel - Foreign pointers - pointer-s8-ref,  Prev: Unit lolevel - Foreign pointers - pointer-offset,  Up: Unit lolevel - Foreign pointers

31.1.12 pointer-u8-ref
----------------------


[procedure] (pointer-u8-ref PTR)
 Returns the unsigned byte at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s8-ref,  Next: Unit lolevel - Foreign pointers - pointer-u16-ref,  Prev: Unit lolevel - Foreign pointers - pointer-u8-ref,  Up: Unit lolevel - Foreign pointers

31.1.13 pointer-s8-ref
----------------------


[procedure] (pointer-s8-ref PTR)
 Returns the signed byte at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u16-ref,  Next: Unit lolevel - Foreign pointers - pointer-s16-ref,  Prev: Unit lolevel - Foreign pointers - pointer-s8-ref,  Up: Unit lolevel - Foreign pointers

31.1.14 pointer-u16-ref
-----------------------


[procedure] (pointer-u16-ref PTR)
 Returns the unsigned 16-bit integer at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s16-ref,  Next: Unit lolevel - Foreign pointers - pointer-u32-ref,  Prev: Unit lolevel - Foreign pointers - pointer-u16-ref,  Up: Unit lolevel - Foreign pointers

31.1.15 pointer-s16-ref
-----------------------


[procedure] (pointer-s16-ref PTR)
 Returns the signed 16-bit integer at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u32-ref,  Next: Unit lolevel - Foreign pointers - pointer-s32-ref,  Prev: Unit lolevel - Foreign pointers - pointer-s16-ref,  Up: Unit lolevel - Foreign pointers

31.1.16 pointer-u32-ref
-----------------------


[procedure] (pointer-u32-ref PTR)
 Returns the unsigned 32-bit integer at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s32-ref,  Next: Unit lolevel - Foreign pointers - pointer-f32-ref,  Prev: Unit lolevel - Foreign pointers - pointer-u32-ref,  Up: Unit lolevel - Foreign pointers

31.1.17 pointer-s32-ref
-----------------------


[procedure] (pointer-s32-ref PTR)
 Returns the signed 32-bit integer at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-f32-ref,  Next: Unit lolevel - Foreign pointers - pointer-f64-ref,  Prev: Unit lolevel - Foreign pointers - pointer-s32-ref,  Up: Unit lolevel - Foreign pointers

31.1.18 pointer-f32-ref
-----------------------


[procedure] (pointer-f32-ref PTR)
 Returns the 32-bit float at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-f64-ref,  Next: Unit lolevel - Foreign pointers - pointer-u8-set!,  Prev: Unit lolevel - Foreign pointers - pointer-f32-ref,  Up: Unit lolevel - Foreign pointers

31.1.19 pointer-f64-ref
-----------------------


[procedure] (pointer-f64-ref PTR)
 Returns the 64-bit double at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u8-set!,  Next: Unit lolevel - Foreign pointers - pointer-s8-set!,  Prev: Unit lolevel - Foreign pointers - pointer-f64-ref,  Up: Unit lolevel - Foreign pointers

31.1.20 pointer-u8-set!
-----------------------


[procedure] (pointer-u8-set! PTR N)
[procedure] (set! (pointer-u8-ref PTR) N)
 Stores the unsigned byte `N' at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s8-set!,  Next: Unit lolevel - Foreign pointers - pointer-u16-set!,  Prev: Unit lolevel - Foreign pointers - pointer-u8-set!,  Up: Unit lolevel - Foreign pointers

31.1.21 pointer-s8-set!
-----------------------


[procedure] (pointer-s8-set! PTR N)
[procedure] (set! (pointer-s8-ref PTR) N)
 Stores the signed byte `N' at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u16-set!,  Next: Unit lolevel - Foreign pointers - pointer-s16-set!,  Prev: Unit lolevel - Foreign pointers - pointer-s8-set!,  Up: Unit lolevel - Foreign pointers

31.1.22 pointer-u16-set!
------------------------


[procedure] (pointer-u16-set! PTR N)
[procedure] (set! (pointer-u16-ref PTR) N)
 Stores the unsigned 16-bit integer `N' at the address designated by
`PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s16-set!,  Next: Unit lolevel - Foreign pointers - pointer-u32-set!,  Prev: Unit lolevel - Foreign pointers - pointer-u16-set!,  Up: Unit lolevel - Foreign pointers

31.1.23 pointer-s16-set!
------------------------


[procedure] (pointer-s16-set! PTR N)
[procedure] (set! (pointer-s16-ref PTR) N)
 Stores the signed 16-bit integer `N' at the address designated by
`PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-u32-set!,  Next: Unit lolevel - Foreign pointers - pointer-s32-set!,  Prev: Unit lolevel - Foreign pointers - pointer-s16-set!,  Up: Unit lolevel - Foreign pointers

31.1.24 pointer-u32-set!
------------------------


[procedure] (pointer-u32-set! PTR N)
[procedure] (set! (pointer-u32-ref PTR) N)
 Stores the unsigned 32-bit integer `N' at the address designated by
`PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-s32-set!,  Next: Unit lolevel - Foreign pointers - pointer-f32-set!,  Prev: Unit lolevel - Foreign pointers - pointer-u32-set!,  Up: Unit lolevel - Foreign pointers

31.1.25 pointer-s32-set!
------------------------


[procedure] (pointer-s32-set! PTR N)
[procedure] (set! (pointer-s32-ref PTR) N)
 Stores the 32-bit integer `N' at the address designated by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-f32-set!,  Next: Unit lolevel - Foreign pointers - pointer-f64-set!,  Prev: Unit lolevel - Foreign pointers - pointer-s32-set!,  Up: Unit lolevel - Foreign pointers

31.1.26 pointer-f32-set!
------------------------


[procedure] (pointer-f32-set! PTR N)
[procedure] (set! (pointer-f32-ref PTR) N)
 Stores the 32-bit floating-point number `N' at the address designated
by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - pointer-f64-set!,  Next: Unit lolevel - Foreign pointers - align-to-word,  Prev: Unit lolevel - Foreign pointers - pointer-f32-set!,  Up: Unit lolevel - Foreign pointers

31.1.27 pointer-f64-set!
------------------------


[procedure] (pointer-f64-set! PTR N)
[procedure] (set! (pointer-f64-ref PTR) N)
 Stores the 64-bit floating-point number `N' at the address designated
by `PTR'.


File: chicken.info,  Node: Unit lolevel - Foreign pointers - align-to-word,  Prev: Unit lolevel - Foreign pointers - pointer-f64-set!,  Up: Unit lolevel - Foreign pointers

31.1.28 align-to-word
---------------------


[procedure] (align-to-word PTR-OR-INT)
 Accepts either a machine pointer or an integer as argument and returns
a new pointer or integer aligned to the native word size of the host
platform.


File: chicken.info,  Node: Unit lolevel - Tagged pointers,  Next: Unit lolevel - Extending procedures with data,  Prev: Unit lolevel - Foreign pointers,  Up: Unit lolevel

31.2 Tagged pointers
====================

* Menu:

* Unit lolevel - Tagged pointers - tag-pointer::
* Unit lolevel - Tagged pointers - tagged-pointer?::
* Unit lolevel - Tagged pointers - pointer-tag::

   _Tagged_ pointers are foreign pointer objects with an extra tag
object.


File: chicken.info,  Node: Unit lolevel - Tagged pointers - tag-pointer,  Next: Unit lolevel - Tagged pointers - tagged-pointer?,  Up: Unit lolevel - Tagged pointers

31.2.1 tag-pointer
------------------


[procedure] (tag-pointer PTR TAG)
 Creates a new tagged pointer object from the foreign pointer `PTR'
with the tag `TAG', which may an arbitrary Scheme object.


File: chicken.info,  Node: Unit lolevel - Tagged pointers - tagged-pointer?,  Next: Unit lolevel - Tagged pointers - pointer-tag,  Prev: Unit lolevel - Tagged pointers - tag-pointer,  Up: Unit lolevel - Tagged pointers

31.2.2 tagged-pointer?
----------------------


[procedure] (tagged-pointer? X TAG)
 Returns `#t', if `X' is a tagged pointer object with the tag `TAG'
(using an `eq?' comparison), or `#f' otherwise.


File: chicken.info,  Node: Unit lolevel - Tagged pointers - pointer-tag,  Prev: Unit lolevel - Tagged pointers - tagged-pointer?,  Up: Unit lolevel - Tagged pointers

31.2.3 pointer-tag
------------------


[procedure] (pointer-tag PTR)
 If `PTR' is a tagged pointer object, its tag is returned. If `PTR' is
a normal, untagged foreign pointer object `#f' is returned. Otherwise
an error is signalled.


File: chicken.info,  Node: Unit lolevel - Extending procedures with data,  Next: Unit lolevel - Data in unmanaged memory,  Prev: Unit lolevel - Tagged pointers,  Up: Unit lolevel

31.3 Extending procedures with data
===================================

* Menu:

* Unit lolevel - Extending procedures with data - extend-procedure::
* Unit lolevel - Extending procedures with data - extended-procedure?::
* Unit lolevel - Extending procedures with data - procedure-data::
* Unit lolevel - Extending procedures with data - set-procedure-data!::


File: chicken.info,  Node: Unit lolevel - Extending procedures with data - extend-procedure,  Next: Unit lolevel - Extending procedures with data - extended-procedure?,  Up: Unit lolevel - Extending procedures with data

31.3.1 extend-procedure
-----------------------


[procedure] (extend-procedure PROCEDURE X)
 Returns a copy of the procedure `PROCEDURE' which contains an
additional data slot initialized to `X'. If `PROCEDURE' is already an
extended procedure, then its data slot is changed to contain `X' and
the same procedure is returned.


File: chicken.info,  Node: Unit lolevel - Extending procedures with data - extended-procedure?,  Next: Unit lolevel - Extending procedures with data - procedure-data,  Prev: Unit lolevel - Extending procedures with data - extend-procedure,  Up: Unit lolevel - Extending procedures with data

31.3.2 extended-procedure?
--------------------------


[procedure] (extended-procedure? PROCEDURE)
 Returns `#t' if `PROCEDURE' is an extended procedure, or `#f'
otherwise.


File: chicken.info,  Node: Unit lolevel - Extending procedures with data - procedure-data,  Next: Unit lolevel - Extending procedures with data - set-procedure-data!,  Prev: Unit lolevel - Extending procedures with data - extended-procedure?,  Up: Unit lolevel - Extending procedures with data

31.3.3 procedure-data
---------------------


[procedure] (procedure-data PROCEDURE)
 Returns the data object contained in the extended procedure
`PROCEDURE', or `#f' if it is not an extended procedure.


File: chicken.info,  Node: Unit lolevel - Extending procedures with data - set-procedure-data!,  Prev: Unit lolevel - Extending procedures with data - procedure-data,  Up: Unit lolevel - Extending procedures with data

31.3.4 set-procedure-data!
--------------------------


[procedure] (set-procedure-data! PROCEDURE X)
 Changes the data object contained in the extended procedure
`PROCEDURE' to `X'.

     (*define* *foo*
       (*letrec* ((f (*lambda* () (procedure-data x)))
                (x #f) )
         (*set!* x (extend-procedure f 123))
         x) )
     (foo)                                         =*=>* 123
     (set-procedure-data! foo 'hello)
     (foo)                                         =*=>* hello


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory,  Next: Unit lolevel - Locatives,  Prev: Unit lolevel - Extending procedures with data,  Up: Unit lolevel

31.4 Data in unmanaged memory
=============================

* Menu:

* Unit lolevel - Data in unmanaged memory - object-evict::
* Unit lolevel - Data in unmanaged memory - object-evict-to-location::
* Unit lolevel - Data in unmanaged memory - object-evicted?::
* Unit lolevel - Data in unmanaged memory - object-size::
* Unit lolevel - Data in unmanaged memory - object-release::
* Unit lolevel - Data in unmanaged memory - object-unevict::


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-evict,  Next: Unit lolevel - Data in unmanaged memory - object-evict-to-location,  Up: Unit lolevel - Data in unmanaged memory

31.4.1 object-evict
-------------------


[procedure] (object-evict X [ALLOCATOR])
 Copies the object `X' recursively into the memory pointed to by the
foreign pointer object returned by `ALLOCATOR', which should be a
procedure of a single argument (the number of bytes to allocate). The
freshly copied object is returned.  This facility allows moving
arbitrary objects into static memory, but care should be taken when
mutating evicted data: setting slots in evicted vector-like objects to
non-evicted data is not allowed. It is possible to set characters/bytes
in evicted strings or byte-vectors, though.  It is advisable not to
evict ports, because they might be mutated by certain file-operations.
`object-evict' is able to handle circular and shared structures, but
evicted symbols are no longer unique: a fresh copy of the symbol is
created, so

     (*define* *x* 'foo)
     (*define* *y* (object-evict 'foo))
     y                              =*=>* foo
     (eq? x y)                      =*=>* #f
     (*define* *z* (object-evict '(bar bar)))
     (eq? (car z) (cadr z))         =*=>* #t
The `ALLOCATOR' defaults to `allocate'.


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-evict-to-location,  Next: Unit lolevel - Data in unmanaged memory - object-evicted?,  Prev: Unit lolevel - Data in unmanaged memory - object-evict,  Up: Unit lolevel - Data in unmanaged memory

31.4.2 object-evict-to-location
-------------------------------


[procedure] (object-evict-to-location X PTR [LIMIT])
 As `object-evict' but moves the object at the address pointed to by
the machine pointer `PTR'. If the number of copied bytes exceeds the
optional `LIMIT' then an error is signalled (specifically a composite
condition of types `exn' and `evict'. The latter provides a `limit'
property which holds the exceeded limit. Two values are returned: the
evicted object and a new pointer pointing to the first free address
after the evicted object.


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-evicted?,  Next: Unit lolevel - Data in unmanaged memory - object-size,  Prev: Unit lolevel - Data in unmanaged memory - object-evict-to-location,  Up: Unit lolevel - Data in unmanaged memory

31.4.3 object-evicted?
----------------------


[procedure] (object-evicted? X)
 Returns `#t' if `X' is a non-immediate evicted data object, or `#f'
otherwise.


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-size,  Next: Unit lolevel - Data in unmanaged memory - object-release,  Prev: Unit lolevel - Data in unmanaged memory - object-evicted?,  Up: Unit lolevel - Data in unmanaged memory

31.4.4 object-size
------------------


[procedure] (object-size X)
 Returns the number of bytes that would be needed to evict the data
object `X'.


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-release,  Next: Unit lolevel - Data in unmanaged memory - object-unevict,  Prev: Unit lolevel - Data in unmanaged memory - object-size,  Up: Unit lolevel - Data in unmanaged memory

31.4.5 object-release
---------------------


[procedure] (object-release X [RELEASER])
 Frees memory occupied by the evicted object `X' recursively.
`RELEASER' should be a procedure of a single argument (a foreign
pointer object to the static memory to be freed) and defaults to `free'.


File: chicken.info,  Node: Unit lolevel - Data in unmanaged memory - object-unevict,  Prev: Unit lolevel - Data in unmanaged memory - object-release,  Up: Unit lolevel - Data in unmanaged memory

31.4.6 object-unevict
---------------------


[procedure] (object-unevict X [FULL])
 Copies the object `X' and nested objects back into the normal Scheme
heap.  Symbols are re-interned into the symbol table. Strings and
byte-vectors are not copied, unless `FULL' is given and not `#f'.


File: chicken.info,  Node: Unit lolevel - Locatives,  Next: Unit lolevel - Accessing toplevel variables,  Prev: Unit lolevel - Data in unmanaged memory,  Up: Unit lolevel

31.5 Locatives
==============

* Menu:

* Unit lolevel - Locatives - make-locative::
* Unit lolevel - Locatives - make-weak-locative::
* Unit lolevel - Locatives - locative?::
* Unit lolevel - Locatives - locative-ref::
* Unit lolevel - Locatives - locative-set!::
* Unit lolevel - Locatives - locative->object::

   A _locative_ is an object that points to an element of a containing
object, much like a _pointer_ in low-level, imperative programming
languages like _C_. The element can be accessed and changed indirectly,
by performing access or change operations on the locative. The
container object can be computed by calling the `location->object'
procedure.

   Locatives may be passed to foreign procedures that expect pointer
arguments. The effect of creating locatives for evicted data (see
`object-evict') is undefined.


File: chicken.info,  Node: Unit lolevel - Locatives - make-locative,  Next: Unit lolevel - Locatives - make-weak-locative,  Up: Unit lolevel - Locatives

31.5.1 make-locative
--------------------


[procedure] (make-locative EXP [INDEX])
 Creates a locative that refers to the element of the non-immediate
object `EXP' at position `INDEX'. `EXP' may be a vector, pair, string,
blob, SRFI-4 number-vector, or record. `INDEX' should be a fixnum.
`INDEX' defaults to 0.


File: chicken.info,  Node: Unit lolevel - Locatives - make-weak-locative,  Next: Unit lolevel - Locatives - locative?,  Prev: Unit lolevel - Locatives - make-locative,  Up: Unit lolevel - Locatives

31.5.2 make-weak-locative
-------------------------


[procedure] (make-weak-locative EXP [INDEX])
 Creates a _weak_ locative. Even though the locative refers to an
element of a container object, the container object will still be
reclaimed by garbage collection if no other references to it exist.


File: chicken.info,  Node: Unit lolevel - Locatives - locative?,  Next: Unit lolevel - Locatives - locative-ref,  Prev: Unit lolevel - Locatives - make-weak-locative,  Up: Unit lolevel - Locatives

31.5.3 locative?
----------------


[procedure] (locative? X)
 Returns `#t' if `X' is a locative, or `#f' otherwise.


File: chicken.info,  Node: Unit lolevel - Locatives - locative-ref,  Next: Unit lolevel - Locatives - locative-set!,  Prev: Unit lolevel - Locatives - locative?,  Up: Unit lolevel - Locatives

31.5.4 locative-ref
-------------------


[procedure] (locative-ref LOC)
 Returns the element to which the locative `LOC' refers. If the
containing object has been reclaimed by garbage collection, an error is
signalled.


File: chicken.info,  Node: Unit lolevel - Locatives - locative-set!,  Next: Unit lolevel - Locatives - locative->object,  Prev: Unit lolevel - Locatives - locative-ref,  Up: Unit lolevel - Locatives

31.5.5 locative-set!
--------------------


[procedure] (locative-set! LOC X)
[procedure] (set! (locative-ref LOC) X)
 Changes the element to which the locative `LOC' refers to `X'. If the
containing object has been reclaimed by garbage collection, an error is
signalled.


File: chicken.info,  Node: Unit lolevel - Locatives - locative->object,  Prev: Unit lolevel - Locatives - locative-set!,  Up: Unit lolevel - Locatives

31.5.6 locative->object
-----------------------


[procedure] (locative->object LOC)
 Returns the object that contains the element referred to by `LOC' or
`#f' if the container has been reclaimed by garbage collection.


File: chicken.info,  Node: Unit lolevel - Accessing toplevel variables,  Next: Unit lolevel - Low-level data access,  Prev: Unit lolevel - Locatives,  Up: Unit lolevel

31.6 Accessing toplevel variables
=================================

* Menu:

* Unit lolevel - Accessing toplevel variables - global-bound?::
* Unit lolevel - Accessing toplevel variables - global-ref::
* Unit lolevel - Accessing toplevel variables - global-set!::


File: chicken.info,  Node: Unit lolevel - Accessing toplevel variables - global-bound?,  Next: Unit lolevel - Accessing toplevel variables - global-ref,  Up: Unit lolevel - Accessing toplevel variables

31.6.1 global-bound?
--------------------


[procedure] (global-bound? SYMBOL)
 Returns `#t', if the global (_toplevel_) variable with the name
`SYMBOL' is bound to a value, or `#f' otherwise.


File: chicken.info,  Node: Unit lolevel - Accessing toplevel variables - global-ref,  Next: Unit lolevel - Accessing toplevel variables - global-set!,  Prev: Unit lolevel - Accessing toplevel variables - global-bound?,  Up: Unit lolevel - Accessing toplevel variables

31.6.2 global-ref
-----------------


[procedure] (global-ref SYMBOL)
 Returns the value of the global variable `SYMBOL'. If no variable
under that name is bound, an error is signalled.

Note that it is not possible to access a toplevel binding with
`global-ref' or `global-set!' if it has been hidden in compiled code
via `(declare (hide ...))', or if the code has been compiled in `block'
mode.


File: chicken.info,  Node: Unit lolevel - Accessing toplevel variables - global-set!,  Prev: Unit lolevel - Accessing toplevel variables - global-ref,  Up: Unit lolevel - Accessing toplevel variables

31.6.3 global-set!
------------------


[procedure] (global-set! SYMBOL X)
[procedure] (set! (global-ref SYMBOL) X)
 Sets the global variable named `SYMBOL' to the value `X'.


File: chicken.info,  Node: Unit lolevel - Low-level data access,  Next: Unit lolevel - Procedure-call- and variable reference hooks,  Prev: Unit lolevel - Accessing toplevel variables,  Up: Unit lolevel

31.7 Low-level data access
==========================

* Menu:

* Unit lolevel - Low-level data access - block-ref::
* Unit lolevel - Low-level data access - block-set!::
* Unit lolevel - Low-level data access - object-copy::
* Unit lolevel - Low-level data access - make-record-instance::
* Unit lolevel - Low-level data access - move-memory!::
* Unit lolevel - Low-level data access - number-of-bytes::
* Unit lolevel - Low-level data access - number-of-slots::
* Unit lolevel - Low-level data access - record-instance?::
* Unit lolevel - Low-level data access - record->vector::


File: chicken.info,  Node: Unit lolevel - Low-level data access - block-ref,  Next: Unit lolevel - Low-level data access - block-set!,  Up: Unit lolevel - Low-level data access

31.7.1 block-ref
----------------


[procedure] (block-ref BLOCK INDEX)
 Returns the contents of the `INDEX'th slot of the object `BLOCK'.
`BLOCK' may be a vector, record structure, pair or symbol.


File: chicken.info,  Node: Unit lolevel - Low-level data access - block-set!,  Next: Unit lolevel - Low-level data access - object-copy,  Prev: Unit lolevel - Low-level data access - block-ref,  Up: Unit lolevel - Low-level data access

31.7.2 block-set!
-----------------


[procedure] (block-set! BLOCK INDEX X)
[procedure] (set! (block-ref BLOCK INDEX) X)
 Sets the contents of the `INDEX'th slot of the object `BLOCK' to the
value of `X'.  `BLOCK' may be a vector, record structure, pair or
symbol.


File: chicken.info,  Node: Unit lolevel - Low-level data access - object-copy,  Next: Unit lolevel - Low-level data access - make-record-instance,  Prev: Unit lolevel - Low-level data access - block-set!,  Up: Unit lolevel - Low-level data access

31.7.3 object-copy
------------------


[procedure] (object-copy X)
 Copies `X' recursively and returns the fresh copy. Objects allocated
in static memory are copied back into garbage collected storage.


File: chicken.info,  Node: Unit lolevel - Low-level data access - make-record-instance,  Next: Unit lolevel - Low-level data access - move-memory!,  Prev: Unit lolevel - Low-level data access - object-copy,  Up: Unit lolevel - Low-level data access

31.7.4 make-record-instance
---------------------------


[procedure] (make-record-instance SYMBOL ARG1 ...)
 Returns a new instance of the record type `SYMBOL', with its slots
initialized to `ARG1 ...'.  To illustrate:

     (define-record point x y)
expands into something quite similar to:

     (*begin*
       (*define* (*make-point* x y)
         (make-record-instance 'point x y) )
       (*define* (*point?* x)
         (*and* (record-instance? x)
              (eq? 'point (block-ref x 0)) ) )
       (*define* (*point-x* p) (block-ref p 1))
       (*define* (*point-x-set!* p x) (block-set! p 1 x))
       (*define* (*point-y* p) (block-ref p 2))
       (*define* (*point-y-set!* p y) (block-set! p 1 y)) )


File: chicken.info,  Node: Unit lolevel - Low-level data access - move-memory!,  Next: Unit lolevel - Low-level data access - number-of-bytes,  Prev: Unit lolevel - Low-level data access - make-record-instance,  Up: Unit lolevel - Low-level data access

31.7.5 move-memory!
-------------------


[procedure] (move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]])
 Copies `BYTES' bytes of memory from `FROM' to `TO'. `FROM' and `TO'
may be strings, primitive byte-vectors, SRFI-4 byte-vectors (see:
@ref{Unit srfi-4}), memory mapped files, foreign pointers (as obtained
from a call to `foreign-lambda', for example) or locatives. if `BYTES'
is not given and the size of the source or destination operand is known
then the maximal number of bytes will be copied. Moving memory to the
storage returned by locatives will cause havoc,  if the locative refers
to containers of non-immediate data, like vectors or pairs.

The additional fourth and fifth argument specify starting offsets  (in
bytes) for the source and destination arguments.


File: chicken.info,  Node: Unit lolevel - Low-level data access - number-of-bytes,  Next: Unit lolevel - Low-level data access - number-of-slots,  Prev: Unit lolevel - Low-level data access - move-memory!,  Up: Unit lolevel - Low-level data access

31.7.6 number-of-bytes
----------------------


[procedure] (number-of-bytes BLOCK)
 Returns the number of bytes that the object `BLOCK' contains. `BLOCK'
may be any non-immediate value.


File: chicken.info,  Node: Unit lolevel - Low-level data access - number-of-slots,  Next: Unit lolevel - Low-level data access - record-instance?,  Prev: Unit lolevel - Low-level data access - number-of-bytes,  Up: Unit lolevel - Low-level data access

31.7.7 number-of-slots
----------------------


[procedure] (number-of-slots BLOCK)
 Returns the number of slots that the object `BLOCK' contains. `BLOCK'
may be a vector, record structure, pair or symbol.


File: chicken.info,  Node: Unit lolevel - Low-level data access - record-instance?,  Next: Unit lolevel - Low-level data access - record->vector,  Prev: Unit lolevel - Low-level data access - number-of-slots,  Up: Unit lolevel - Low-level data access

31.7.8 record-instance?
-----------------------


[procedure] (record-instance? X)
 Returns `#t' if `X' is an instance of a record type. See also:
`make-record-instance'.


File: chicken.info,  Node: Unit lolevel - Low-level data access - record->vector,  Prev: Unit lolevel - Low-level data access - record-instance?,  Up: Unit lolevel - Low-level data access

31.7.9 record->vector
---------------------


[procedure] (record->vector BLOCK)
 Returns a new vector with the type and the elements of the record
`BLOCK'.


File: chicken.info,  Node: Unit lolevel - Procedure-call- and variable reference hooks,  Next: Unit lolevel - Magic,  Prev: Unit lolevel - Low-level data access,  Up: Unit lolevel

31.8 Procedure-call- and variable reference hooks
=================================================

* Menu:

* Unit lolevel - Procedure-call- and variable reference hooks - set-invalid-procedure-call-handler!::
* Unit lolevel - Procedure-call- and variable reference hooks - unbound-variable-value::


File: chicken.info,  Node: Unit lolevel - Procedure-call- and variable reference hooks - set-invalid-procedure-call-handler!,  Next: Unit lolevel - Procedure-call- and variable reference hooks - unbound-variable-value,  Up: Unit lolevel - Procedure-call- and variable reference hooks

31.8.1 set-invalid-procedure-call-handler!
------------------------------------------


[procedure] (set-invalid-procedure-call-handler! PROC)
 Sets an internal hook that is invoked when a call to an object other
than a procedure is executed at runtime. The procedure `PROC' will in
that case be called with two arguments: the object being called and a
list of the passed arguments.

     _;;; Access sequence-elements as in ARC:
     _
     (set-invalid-procedure-call-handler!
       (*lambda* (proc args)
         (*cond* [(string? proc) (apply string-ref proc args)]
               [(vector? proc) (apply vector-ref proc args)]
               [*else* (error *"call of non-procedure"* proc)] ) ) )

     (*"hello"* 4)    =*=>*  #\o
This facility does not work in code compiled with the _unsafe_ setting.


File: chicken.info,  Node: Unit lolevel - Procedure-call- and variable reference hooks - unbound-variable-value,  Prev: Unit lolevel - Procedure-call- and variable reference hooks - set-invalid-procedure-call-handler!,  Up: Unit lolevel - Procedure-call- and variable reference hooks

31.8.2 unbound-variable-value
-----------------------------


[procedure] (unbound-variable-value [X])
 Defines the value that is returned for unbound variables. Normally an
error is signalled, use this procedure to override the check and return
`X' instead. To set the default behavior (of signalling an error), call
`unbound-variable-value' with no arguments.

This facility does not work in code compiled with the _unsafe_ setting.


File: chicken.info,  Node: Unit lolevel - Magic,  Prev: Unit lolevel - Procedure-call- and variable reference hooks,  Up: Unit lolevel

31.9 Magic
==========

* Menu:

* Unit lolevel - Magic - object-become!::
* Unit lolevel - Magic - mutate-procedure::


File: chicken.info,  Node: Unit lolevel - Magic - object-become!,  Next: Unit lolevel - Magic - mutate-procedure,  Up: Unit lolevel - Magic

31.9.1 object-become!
---------------------


[procedure] (object-become! ALIST)
 Changes the identity of the value of the car of each pair in `ALIST'
to the value of the cdr. Both values may not be immediate (i.e. exact
integers, characters, booleans or the empty list).

     (*define* *x* *"i used to be a string"*)
     (*define* *y* '#(*and* now i am a vector))
     (object-become! (list (cons x y)))
     x                                    =*=>* #(*and* now i am a vector)
     y                                    =*=>* #(*and* now i am a vector)
     (eq? x y)                            =*=>* #t
Note: this operation invokes a major garbage collection.

   The effect of using `object-become!' on evicted data (see
`object-evict') is undefined.


File: chicken.info,  Node: Unit lolevel - Magic - mutate-procedure,  Prev: Unit lolevel - Magic - object-become!,  Up: Unit lolevel - Magic

31.9.2 mutate-procedure
-----------------------


[procedure] (mutate-procedure OLD PROC)
 Replaces the procedure `OLD' with the result of calling the
one-argument procedure `PROC'. `PROC' will receive a copy of `OLD' that
will be identical in behaviour to the result of `PROC':

     _;;; Replace arbitrary procedure with tracing one:
     _
     (mutate-procedure my-proc
       (*lambda* (new)
         (*lambda* args
           (printf *"~s called with arguments: ~s~%"* new args)
           (apply new args) ) ) )
Previous: *Note Unit tcp: Unit tcp.

   Next: *Note Interface to external functions and variables: Interface
to external functions and variables.


File: chicken.info,  Node: Interface to external functions and variables,  Next: Accessing external objects,  Prev: Unit lolevel,  Up: Top

32 Interface to external functions and variables
************************************************

   * *Note Accessing external objects: Accessing external objects.

   * *Note Foreign type specifiers: Foreign type specifiers.

   * *Note Embedding: Embedding.

   * *Note Callbacks: Callbacks.

   * *Note Locations: Locations.

   * *Note Other support procedures: Other support procedures.

   * *Note C interface: C interface.

Previous: *Note Supported language: Supported language.

   Next: *Note chicken-setup: chicken-setup.


File: chicken.info,  Node: Accessing external objects,  Next: Foreign type specifiers,  Prev: Interface to external functions and variables,  Up: Top

33 Accessing external objects
*****************************

* Menu:

* Accessing external objects - foreign-code::
* Accessing external objects - foreign-value::
* Accessing external objects - foreign-declare::
* Accessing external objects - define-foreign-type::
* Accessing external objects - define-foreign-variable::
* Accessing external objects - define-foreign-record::
* Accessing external objects - define-foreign-enum::
* Accessing external objects - foreign-lambda::
* Accessing external objects - foreign-lambda*::
* Accessing external objects - foreign-safe-lambda::
* Accessing external objects - foreign-safe-lambda*::
* Accessing external objects - foreign-primitive::


File: chicken.info,  Node: Accessing external objects - foreign-code,  Next: Accessing external objects - foreign-value,  Up: Accessing external objects

33.1 foreign-code
=================


[syntax] (foreign-code STRING ...)
 Executes the embedded C/C++ code `STRING ...', which should be a
sequence of C statements, which are executed and return an unspecified
result.

     (foreign-code *"doSomeInitStuff();"*)     *=>*  #<unspecified>
Code wrapped inside `foreign-code' may not invoke callbacks into Scheme.


File: chicken.info,  Node: Accessing external objects - foreign-value,  Next: Accessing external objects - foreign-declare,  Prev: Accessing external objects - foreign-code,  Up: Accessing external objects

33.2 foreign-value
==================


[syntax] (foreign-value STRING TYPE)
 Evaluates the embedded C/C++ expression `STRING', returning a value of
type given in the foreign-type specifier `TYPE'.

     (print (foreign-value *"my_version_string"* c-string))


File: chicken.info,  Node: Accessing external objects - foreign-declare,  Next: Accessing external objects - define-foreign-type,  Prev: Accessing external objects - foreign-value,  Up: Accessing external objects

33.3 foreign-declare
====================


[syntax] (foreign-declare STRING ...)
 Include given strings verbatim into header of generated file.


File: chicken.info,  Node: Accessing external objects - define-foreign-type,  Next: Accessing external objects - define-foreign-variable,  Prev: Accessing external objects - foreign-declare,  Up: Accessing external objects

33.4 define-foreign-type
========================


[syntax] (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
 Defines an alias for `TYPE' with the name `NAME' (a symbol). `TYPE'
may be a type-specifier or a string naming a C type. The namespace of
foreign type specifiers is separate from the normal Scheme namespace.
The optional arguments `ARGCONVERT' and `RETCONVERT' should evaluate to
procedures that map argument- and result-values to a value that can be
transformed to `TYPE':

     (define-foreign-type char-vector
       nonnull-c-string
       (compose list->string vector->list)
       (compose list->vector string->list) )

     (*define* *strlen*
       (foreign-lambda int *"strlen"* char-vector) )

     (strlen '#(#\a #\b #\c))                      =*=>* 3

     (*define* *memset*
       (foreign-lambda char-vector *"memset"* char-vector char int) )

     (memset '#(#_ #_ #_) #\X 3)                =*=>* #(#\X #\X #\X)
Foreign type-definitions are only visible in the compilation-unit in
which they are defined, so use `include' to use the same definitions in
multiple files.


File: chicken.info,  Node: Accessing external objects - define-foreign-variable,  Next: Accessing external objects - define-foreign-record,  Prev: Accessing external objects - define-foreign-type,  Up: Accessing external objects

33.5 define-foreign-variable
============================


[syntax] (define-foreign-variable NAME TYPE [STRING])
 Defines a foreign variable of name `NAME' (a symbol). `STRING' should
be the real name of a foreign variable or parameterless macro. If
`STRING' is not given, then the variable name `NAME' will be converted
to a string and used instead. All references and assignments (via
`set!') are modified to correctly convert values between Scheme and C
representation. This foreign variable can only be accessed in the
current compilation unit, but the name can be lexically shadowed.  Note
that `STRING' can name an arbitrary C expression. If no assignments are
performed, then `STRING' doesn't even have to specify an lvalue.

     #>
     enum { abc=3, def, ghi }_;
     _<#

     (define-macro (define-simple-foreign-enum . items)
       `(*begin*
          ,@(map (match-lambda
                   [(name realname) `(define-foreign-variable ,name int ,realname)]
                   [name `(define-foreign-variable ,name int)] )
          items) ) )

     (define-simple-foreign-enum abc def ghi)

     ghi                               =*=>* 5


File: chicken.info,  Node: Accessing external objects - define-foreign-record,  Next: Accessing external objects - define-foreign-enum,  Prev: Accessing external objects - define-foreign-variable,  Up: Accessing external objects

33.6 define-foreign-record
==========================

* Menu:

* Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME::
* Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME-set!::
* Accessing external objects - define-foreign-record - constructor::
* Accessing external objects - define-foreign-record - destructor::
* Accessing external objects - define-foreign-record - rename::


[syntax] (define-foreign-record NAME [DECL ...] SLOT ...)
 Defines accessor procedures for a C structure definition. `NAME'
should either be a symbol or a list of the form `(TYPENAME
FOREIGNNAME)'. If `NAME' is a symbol, then a C declaration will be
generated that defines a C struct named `struct NAME'. If `NAME' is a
list, then no struct declaration will be generated and `FOREIGNNAME'
should name an existing C record type. A foreign-type specifier named
`NAME' (or `TYPENAME') will be defined as a pointer to the given C
structure. A `SLOT' definition should be a list of one of the following
forms:


(TYPE SLOTNAME)
 or


(TYPE SLOTNAME SIZE)
 The latter form defines an array of `SIZE' elements of the type `TYPE'
embedded in the structure. For every slot, the following accessor
procedures will be generated:


File: chicken.info,  Node: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME,  Next: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME-set!,  Up: Accessing external objects - define-foreign-record

33.6.1 TYPENAME-SLOTNAME
------------------------


(TYPENAME-SLOTNAME FOREIGN-RECORD-POINTER [INDEX])
 A procedure of one argument (a pointer to a C structure), that returns
the slot value of the slot `SLOTNAME'. If a `SIZE' has been given in
the slot definition, then an additional argument `INDEX' is required
that specifies the index of an array-element.


File: chicken.info,  Node: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME-set!,  Next: Accessing external objects - define-foreign-record - constructor,  Prev: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME,  Up: Accessing external objects - define-foreign-record

33.6.2 TYPENAME-SLOTNAME-set!
-----------------------------



(TYPENAME-SLOTNAME-set! FOREIGN-RECORD-POINTER [INDEX] VALUE)
 A procedure of two arguments (a pointer to a C structure) and a value,
that sets the slot value of the slot `SLOTNAME' in the structure. If a
`SIZE' has been given in the slot definition, then an additional
argument `INDEX' is required for the array index.

If a slot type is of the form `(const ...)', then no setter procedure
will be generated. Slots of the types `(struct ...)' or `(union ...)'
are accessed as pointers to the embedded struct (or union) and no
setter will be generated.

   Additionally, special record-declarations (`DECL ...') may be given,
where each declaration consists of a list of the form `(KEYWORD
ARGUMENT ...)'. The available declarations are:


File: chicken.info,  Node: Accessing external objects - define-foreign-record - constructor,  Next: Accessing external objects - define-foreign-record - destructor,  Prev: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME-set!,  Up: Accessing external objects - define-foreign-record

33.6.3 constructor
------------------


(constructor: NAME)
 Generate a constructor-procedure with no arguments that has the name
`NAME' (a symbol) that returns a pointer to a structure of this type.
The storage will be allocated with `malloc(3)'.


File: chicken.info,  Node: Accessing external objects - define-foreign-record - destructor,  Next: Accessing external objects - define-foreign-record - rename,  Prev: Accessing external objects - define-foreign-record - constructor,  Up: Accessing external objects - define-foreign-record

33.6.4 destructor
-----------------


(destructor: NAME)
 Generate a destructor function with the name `NAME' that takes a
pointer to a structure of this type as its single argument and releases
the storage with `free(3)'. If the argument is `#f', the destructor
procedure does nothing.


File: chicken.info,  Node: Accessing external objects - define-foreign-record - rename,  Prev: Accessing external objects - define-foreign-record - destructor,  Up: Accessing external objects - define-foreign-record

33.6.5 rename
-------------


(rename: EXPRESSION)
 Evaluates `EXPRESSION' at compile-/macro-expansion-time and applies
the result, which should be a procedure, to the string-representation
of the name of each accessor-procedure generated. Another (or the same)
string should be returned, which in turn is taken as the actual name of
the accessor.

An example:

     (require-for-syntax 'srfi-13)

     (define-foreign-record Some_Struct
       (rename: (compose string-downcase (cut string-translate <> *"_"* *"-"*)))
       (constructor: make-some-struct)
       (destructor: free-some-struct)
       (int xCoord)
       (int yCoord) )
   will generate the following procedures:

     (make-some-struct)              --> C-POINTER
     (free-some-struct C-POINTER)

     (some-struct-xcoord C-POINTER)  --> NUMBER
     (some-struct-ycoord C-POINTER)  --> NUMBER

     (some-struct-xcoord-set! C-POINTER NUMBER)
     (some-struct-ycoord-set! C-POINTER NUMBER)


File: chicken.info,  Node: Accessing external objects - define-foreign-enum,  Next: Accessing external objects - foreign-lambda,  Prev: Accessing external objects - define-foreign-record,  Up: Accessing external objects

33.7 define-foreign-enum
========================


[syntax] (define-foreign-enum TYPESPEC [USE-ALIASES] ENUMSPEC ...)
 Defines a foreign type (as with `define-foreign-type') that maps the
elements of a C/C++ enum (or a enum-like list of constants) to and from
a set of symbols.

`TYPESPEC' specifies a foreign type that converts a symbol argument
from the set `ENUMSPEC ...' into the appropriate enum value when passed
as an argument to a foreign function.

   A list of symbols passed as an argument will be combined using
`bitwise-ior'. An empty list will be passed as 0 (zero). Results of the
enum type are automatically converted into a scheme value (note that
combinations are not supported in this case).

   `TYPESPEC' maybe a TYPENAME symbol or a list of the form
`(SCHEMENAME REALTYPE [DEFAULT-SCHEME-VALUE])', where `REALTYPE'
designates the native type used. The default type specification is
`(TYPENAME TYPENAME)'. The `DEFAULT-SCHEME-VALUE' overrides the default
result of mapping from the native type; i.e. when no such mapping
exists. When supplied the form is used unquoted, otherwise the result
is `'()'.

   `ENUMSPEC' is a TYPENAME symbol or a list of the form `(SCHEMENAME
REALTYPE [SCHEME-VALUE])', where `REALTYPE' designates the native type
used. The default enum specification is `(TYPENAME TYPENAME)'. The
`SCHEME-VALUE' overrides the result of mapping from the native type.
When supplied the form is used unquoted, otherwise the `SCHEMENAME'
symbol is returned.

   `USE-ALIASES' is an optional boolean flag that determines whether an
alias or the `SCHEMENAME' is used as the defined foreign variable name.
The default is `#t'.

   Additionally two procedures are defined named `SCHEMENAME->number'
and `number->SCHEMENAME'. `SCHEMENAME->number' takes one argument and
converts a symbol (or a list of symbols) into its numeric value.
`number->SCHEMENAME' takes one argument and converts a numeric value
into its scheme value.

   Note that the specification of a scheme value override
(`SCHEME-VALUE') means the mapping may not be closed!
`(number->SCHEMENAME (SCHEMENAME->number SCHEMENAME))' may not equal
`SCHEMENAME'.

   Here a heavily contrived example:

     #>
     enum foo { a_foo = 4, b_foo, c_foo }_;
     _enum foo bar(enum foo x) { printf(*"%d\n"*, x)_; return b_foo; }
     _<#

     (define-foreign-enum (foo (enum *"foo"*)) a_foo b_foo (c c_foo))

     (*define* *bar* (foreign-lambda foo bar foo))

     (pp (bar '()))
     (pp (bar 'a_foo))
     (pp (bar '(b_foo c)))


File: chicken.info,  Node: Accessing external objects - foreign-lambda,  Next: Accessing external objects - foreign-lambda*,  Prev: Accessing external objects - define-foreign-enum,  Up: Accessing external objects

33.8 foreign-lambda
===================


[syntax] (foreign-lambda RETURNTYPE NAME ARGTYPE ...)
 Represents a binding to an external routine. This form can be used in
the position of an ordinary `lambda' expression. `NAME' specifies the
name of the external procedure and should be a string or a symbol.


File: chicken.info,  Node: Accessing external objects - foreign-lambda*,  Next: Accessing external objects - foreign-safe-lambda,  Prev: Accessing external objects - foreign-lambda,  Up: Accessing external objects

33.9 foreign-lambda*
====================


[syntax] (foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
 Similar to `foreign-lambda', but instead of generating code to call an
external function, the body of the C procedure is directly given in
`STRING ...':

     (*define* *my-strlen*
       (foreign-lambda* int ((c-string str))
         *"int n = 0;
          while(*(str++)) ++n;
          C_return(n);"*) )

     (my-strlen *"one two three"*)             =*=>* 13
For obscure technical reasons you should use the `C_return' macro
instead of the normal `return' statement to return a result from the
foreign lambda body as some cleanup code has to be run before execution
commences in the calling code.


File: chicken.info,  Node: Accessing external objects - foreign-safe-lambda,  Next: Accessing external objects - foreign-safe-lambda*,  Prev: Accessing external objects - foreign-lambda*,  Up: Accessing external objects

33.10 foreign-safe-lambda
=========================


[syntax] (foreign-safe-lambda RETURNTYPE NAME ARGTYPE ...)
 This is similar to `foreign-lambda', but also allows the called
function to call Scheme functions and allocate Scheme data-objects. See
*Note Callbacks: Callbacks.


File: chicken.info,  Node: Accessing external objects - foreign-safe-lambda*,  Next: Accessing external objects - foreign-primitive,  Prev: Accessing external objects - foreign-safe-lambda,  Up: Accessing external objects

33.11 foreign-safe-lambda*
==========================


[syntax] (foreign-safe-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)
 This is similar to `foreign-lambda*', but also allows the called
function to call Scheme functions and allocate Scheme data-objects. See
*Note Callbacks: Callbacks.


File: chicken.info,  Node: Accessing external objects - foreign-primitive,  Prev: Accessing external objects - foreign-safe-lambda*,  Up: Accessing external objects

33.12 foreign-primitive
=======================


[syntax] (foreign-primitive [RETURNTYPE] ((ARGTYPE VARIABLE) ...) STRING ...)
 This is also similar to `foreign-lambda*' but the code will be
executed in a _primitive_ CPS context, which means it will not actually
return, but call it's continuation on exit. This means that code inside
this form may allocate Scheme data on the C stack (the _nursery_) with
`C_alloc' (see below). If the `RETURNTYPE' is omitted it defaults to
`void'. You can return multiple values inside the body of the
`foreign-primitive' form by calling this C function:

     C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)
where `N' is the number of values to be returned, and `X1, ...' are the
results, which should be Scheme data objects. When returning multiple
values, the return-type should be omitted.

   Previous: *Note Interface to external functions and variables:
Interface to external functions and variables.

   Next: *Note Foreign type specifiers: Foreign type specifiers.


File: chicken.info,  Node: Foreign type specifiers,  Next: Embedding,  Prev: Accessing external objects,  Up: Top

34 Foreign type specifiers
**************************

* Menu:

* Foreign type specifiers - scheme-object::
* Foreign type specifiers - bool::
* Foreign type specifiers - byte unsigned-byte::
* Foreign type specifiers - char unsigned-char::
* Foreign type specifiers - short unsigned-short::
* Foreign type specifiers - int unsigned-int int32 unsigned-int32::
* Foreign type specifiers - integer unsigned-integer integer32 unsigned-integer32 integer64::
* Foreign type specifiers - long unsigned-long::
* Foreign type specifiers - float double::
* Foreign type specifiers - number::
* Foreign type specifiers - symbol::
* Foreign type specifiers - scheme-pointer::
* Foreign type specifiers - nonnull-scheme-pointer::
* Foreign type specifiers - c-pointer::
* Foreign type specifiers - nonnull-c-pointer::
* Foreign type specifiers - blob::
* Foreign type specifiers - nonnull-blob::
* Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector::
* Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector::
* Foreign type specifiers - c-string::
* Foreign type specifiers - nonnull-c-string::
* Foreign type specifiers - [nonnull-] c-string*::
* Foreign type specifiers - [nonnull-] unsigned-c-string[*]::
* Foreign type specifiers - c-string-list::
* Foreign type specifiers - c-string-list*::
* Foreign type specifiers - void::
* Foreign type specifiers - ;const TYPE;::
* Foreign type specifiers - ;enum NAME;::
* Foreign type specifiers - ;c-pointer TYPE;::
* Foreign type specifiers - ;nonnull-c-pointer TYPE;::
* Foreign type specifiers - ;ref TYPE;::
* Foreign type specifiers - ;struct NAME;::
* Foreign type specifiers - ;template TYPE ARGTYPE ;;;;::
* Foreign type specifiers - ;union NAME;::
* Foreign type specifiers - ;instance CNAME SCHEMECLASS;::
* Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;::
* Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];::
* Foreign type specifiers - Mappings::

   Here is a list of valid foreign type specifiers:


File: chicken.info,  Node: Foreign type specifiers - scheme-object,  Next: Foreign type specifiers - bool,  Up: Foreign type specifiers

34.1 scheme-object
==================

An arbitrary Scheme data object (immediate or non-immediate).


File: chicken.info,  Node: Foreign type specifiers - bool,  Next: Foreign type specifiers - byte unsigned-byte,  Prev: Foreign type specifiers - scheme-object,  Up: Foreign type specifiers

34.2 bool
=========

As argument: any value (`#f' is false, anything else is true).

   As result: anything different from 0 and the `NULL' pointer is `#t'.


File: chicken.info,  Node: Foreign type specifiers - byte unsigned-byte,  Next: Foreign type specifiers - char unsigned-char,  Prev: Foreign type specifiers - bool,  Up: Foreign type specifiers

34.3 byte unsigned-byte
=======================

A byte.


File: chicken.info,  Node: Foreign type specifiers - char unsigned-char,  Next: Foreign type specifiers - short unsigned-short,  Prev: Foreign type specifiers - byte unsigned-byte,  Up: Foreign type specifiers

34.4 char unsigned-char
=======================

A character.


File: chicken.info,  Node: Foreign type specifiers - short unsigned-short,  Next: Foreign type specifiers - int unsigned-int int32 unsigned-int32,  Prev: Foreign type specifiers - char unsigned-char,  Up: Foreign type specifiers

34.5 short unsigned-short
=========================

A short integer number.


File: chicken.info,  Node: Foreign type specifiers - int unsigned-int int32 unsigned-int32,  Next: Foreign type specifiers - integer unsigned-integer integer32 unsigned-integer32 integer64,  Prev: Foreign type specifiers - short unsigned-short,  Up: Foreign type specifiers

34.6 int unsigned-int int32 unsigned-int32
==========================================

An small integer number in fixnum range (at least 30 bit).


File: chicken.info,  Node: Foreign type specifiers - integer unsigned-integer integer32 unsigned-integer32 integer64,  Next: Foreign type specifiers - long unsigned-long,  Prev: Foreign type specifiers - int unsigned-int int32 unsigned-int32,  Up: Foreign type specifiers

34.7 integer unsigned-integer integer32 unsigned-integer32 integer64
====================================================================

Either a fixnum or a flonum in the range of a (unsigned) machine _int_
or with 32/64 bit width.


File: chicken.info,  Node: Foreign type specifiers - long unsigned-long,  Next: Foreign type specifiers - float double,  Prev: Foreign type specifiers - integer unsigned-integer integer32 unsigned-integer32 integer64,  Up: Foreign type specifiers

34.8 long unsigned-long
=======================

Either a fixnum or a flonum in the range of a (unsigned) machine _long_
or with 32 bit width.


File: chicken.info,  Node: Foreign type specifiers - float double,  Next: Foreign type specifiers - number,  Prev: Foreign type specifiers - long unsigned-long,  Up: Foreign type specifiers

34.9 float double
=================

A floating-point number. If an exact integer is passed as an argument,
then it is automatically converted to a float.


File: chicken.info,  Node: Foreign type specifiers - number,  Next: Foreign type specifiers - symbol,  Prev: Foreign type specifiers - float double,  Up: Foreign type specifiers

34.10 number
============

A floating-point number. Similar to `double', but when used as a result
type, then either an exact integer or a floating-point number is
returned, depending on whether the result fits into an exact integer or
not.


File: chicken.info,  Node: Foreign type specifiers - symbol,  Next: Foreign type specifiers - scheme-pointer,  Prev: Foreign type specifiers - number,  Up: Foreign type specifiers

34.11 symbol
============

A symbol, which will be passed to foreign code as a zero-terminated
string.

   When declared as the result of foreign code, the result should be a
string and a symbol with the same name will be interned in the symbol
table (and returned to the caller).


File: chicken.info,  Node: Foreign type specifiers - scheme-pointer,  Next: Foreign type specifiers - nonnull-scheme-pointer,  Prev: Foreign type specifiers - symbol,  Up: Foreign type specifiers

34.12 scheme-pointer
====================

An untyped pointer to the contents of a non-immediate Scheme object
(not allowed as return type). The value `#f' is also allowed and is
passed as a `NULL' pointer.

   Don't confuse this type with `(c-pointer ...)' which means something
different (a machine-pointer object).


File: chicken.info,  Node: Foreign type specifiers - nonnull-scheme-pointer,  Next: Foreign type specifiers - c-pointer,  Prev: Foreign type specifiers - scheme-pointer,  Up: Foreign type specifiers

34.13 nonnull-scheme-pointer
============================

As `scheme-pointer', but guaranteed not to be `#f'.

   Don't confuse this type with `(nonnull-c-pointer ...)' which means
something different (a machine-pointer object).


File: chicken.info,  Node: Foreign type specifiers - c-pointer,  Next: Foreign type specifiers - nonnull-c-pointer,  Prev: Foreign type specifiers - nonnull-scheme-pointer,  Up: Foreign type specifiers

34.14 c-pointer
===============

An untyped operating-system pointer or a locative. The value `#f' is
also allowed and is passed as a `NULL' pointer. If uses as the type of
a return value, a `NULL' pointer will be returned as `#f'.


File: chicken.info,  Node: Foreign type specifiers - nonnull-c-pointer,  Next: Foreign type specifiers - blob,  Prev: Foreign type specifiers - c-pointer,  Up: Foreign type specifiers

34.15 nonnull-c-pointer
=======================

As `c-pointer', but guaranteed not to be `#f/NULL'.


File: chicken.info,  Node: Foreign type specifiers - blob,  Next: Foreign type specifiers - nonnull-blob,  Prev: Foreign type specifiers - nonnull-c-pointer,  Up: Foreign type specifiers

34.16 blob
==========

A blob object, passed as a pointer to its contents. Arguments of type
`blob' may optionally be `#f', which is passed as a NULL pointer.

   This is not allowed as a return type.


File: chicken.info,  Node: Foreign type specifiers - nonnull-blob,  Next: Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector,  Prev: Foreign type specifiers - blob,  Up: Foreign type specifiers

34.17 nonnull-blob
==================

As `blob', but guaranteed not to be `#f'.


File: chicken.info,  Node: Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector,  Next: Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector,  Prev: Foreign type specifiers - nonnull-blob,  Up: Foreign type specifiers

34.18 u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector
===================================================================================

A SRFI-4 number-vector object, passed as a pointer to its contents.

   These type specifiers are not allowed as return types.


File: chicken.info,  Node: Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector,  Next: Foreign type specifiers - c-string,  Prev: Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector,  Up: Foreign type specifiers

34.19 nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector
===================================================================================================================================================

As `u8vector ...', but guaranteed not to be `#f'.


File: chicken.info,  Node: Foreign type specifiers - c-string,  Next: Foreign type specifiers - nonnull-c-string,  Prev: Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector,  Up: Foreign type specifiers

34.20 c-string
==============

A C string (zero-terminated). The value `#f' is also allowed and is
passed as a `NULL' pointer. If uses as the type of a return value, a
`NULL' pointer will be returned as `#f'. Note that the string is copied
(with a zero-byte appended) when passed as an argument to a foreign
function. Also a return value of this type is copied into garbage
collected memory.


File: chicken.info,  Node: Foreign type specifiers - nonnull-c-string,  Next: Foreign type specifiers - [nonnull-] c-string*,  Prev: Foreign type specifiers - c-string,  Up: Foreign type specifiers

34.21 nonnull-c-string
======================

As `c-string', but guaranteed not to be `#f/NULL'.


File: chicken.info,  Node: Foreign type specifiers - [nonnull-] c-string*,  Next: Foreign type specifiers - [nonnull-] unsigned-c-string[*],  Prev: Foreign type specifiers - nonnull-c-string,  Up: Foreign type specifiers

34.22 [nonnull-] c-string*
==========================

Similar to `[nonnull-] c-string', but if used as a result-type, the
pointer returned by the foreign code will be freed (using the
C-libraries `free(1)') after copying. This type specifier is not valid
as a result type for callbacks defined with `define-external'.


File: chicken.info,  Node: Foreign type specifiers - [nonnull-] unsigned-c-string[*],  Next: Foreign type specifiers - c-string-list,  Prev: Foreign type specifiers - [nonnull-] c-string*,  Up: Foreign type specifiers

34.23 [nonnull-] unsigned-c-string[*]
=====================================

Same as `c-string', but maps to the `unsigned char *' C type.


File: chicken.info,  Node: Foreign type specifiers - c-string-list,  Next: Foreign type specifiers - c-string-list*,  Prev: Foreign type specifiers - [nonnull-] unsigned-c-string[*],  Up: Foreign type specifiers

34.24 c-string-list
===================

Expects a pointer to a list of C strings teminated by a `NULL' pointer
and returns a list of strings.

   Only valid as a result type of non-callback functions.


File: chicken.info,  Node: Foreign type specifiers - c-string-list*,  Next: Foreign type specifiers - void,  Prev: Foreign type specifiers - c-string-list,  Up: Foreign type specifiers

34.25 c-string-list*
====================

Similar to `c-string-list' but releases the storage of each string and
the pointer array using `free(1)'.


File: chicken.info,  Node: Foreign type specifiers - void,  Next: Foreign type specifiers - ;const TYPE;,  Prev: Foreign type specifiers - c-string-list*,  Up: Foreign type specifiers

34.26 void
==========

Specifies an undefined return value.

   Not allowed as argument type.


File: chicken.info,  Node: Foreign type specifiers - ;const TYPE;,  Next: Foreign type specifiers - ;enum NAME;,  Prev: Foreign type specifiers - void,  Up: Foreign type specifiers

34.27 (const TYPE)
==================

The foreign type `TYPE' with an additional `const' specifier.


File: chicken.info,  Node: Foreign type specifiers - ;enum NAME;,  Next: Foreign type specifiers - ;c-pointer TYPE;,  Prev: Foreign type specifiers - ;const TYPE;,  Up: Foreign type specifiers

34.28 (enum NAME)
=================

An enumeration type. Handled internally as an `integer'.


File: chicken.info,  Node: Foreign type specifiers - ;c-pointer TYPE;,  Next: Foreign type specifiers - ;nonnull-c-pointer TYPE;,  Prev: Foreign type specifiers - ;enum NAME;,  Up: Foreign type specifiers

34.29 (c-pointer TYPE)
======================

An operating-system pointer or a locative to an object of `TYPE'.


File: chicken.info,  Node: Foreign type specifiers - ;nonnull-c-pointer TYPE;,  Next: Foreign type specifiers - ;ref TYPE;,  Prev: Foreign type specifiers - ;c-pointer TYPE;,  Up: Foreign type specifiers

34.30 (nonnull-c-pointer TYPE)
==============================

As `(c-pointer TYPE)', but guaranteed not to be `#f/NULL'.


File: chicken.info,  Node: Foreign type specifiers - ;ref TYPE;,  Next: Foreign type specifiers - ;struct NAME;,  Prev: Foreign type specifiers - ;nonnull-c-pointer TYPE;,  Up: Foreign type specifiers

34.31 (ref TYPE)
================

A C++ reference type. Reference types are handled the same way as
pointers inside Scheme code.


File: chicken.info,  Node: Foreign type specifiers - ;struct NAME;,  Next: Foreign type specifiers - ;template TYPE ARGTYPE ;;;;,  Prev: Foreign type specifiers - ;ref TYPE;,  Up: Foreign type specifiers

34.32 (struct NAME)
===================

A struct of the name `NAME', which should be a string.

   Structs cannot be directly passed as arguments to foreign function,
neither can they be result values. Pointers to structs are allowed,
though.


File: chicken.info,  Node: Foreign type specifiers - ;template TYPE ARGTYPE ;;;;,  Next: Foreign type specifiers - ;union NAME;,  Prev: Foreign type specifiers - ;struct NAME;,  Up: Foreign type specifiers

34.33 (template TYPE ARGTYPE ...)
=================================

A C++ template type. For example `vector<int>' would be specified as
`(template "vector" int)'.

   Template types cannot be directly passed as arguments or returned as
results.


File: chicken.info,  Node: Foreign type specifiers - ;union NAME;,  Next: Foreign type specifiers - ;instance CNAME SCHEMECLASS;,  Prev: Foreign type specifiers - ;template TYPE ARGTYPE ;;;;,  Up: Foreign type specifiers

34.34 (union NAME)
==================

A union of the name `NAME', which should be a string.

   Unions cannot be directly passed as arguments to foreign function,
neither can they be result values. Pointers to unions are allowed,
though.


File: chicken.info,  Node: Foreign type specifiers - ;instance CNAME SCHEMECLASS;,  Next: Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;,  Prev: Foreign type specifiers - ;union NAME;,  Up: Foreign type specifiers

34.35 (instance CNAME SCHEMECLASS)
==================================

A pointer to a C++ class instance. `CNAME' should designate the name of
the C++ class, and `SCHEMECLASS' should be the class that wraps the
instance pointer. Normally `SCHEMECLASS' should be a subclass of
`<c++-object>'.


File: chicken.info,  Node: Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;,  Next: Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];,  Prev: Foreign type specifiers - ;instance CNAME SCHEMECLASS;,  Up: Foreign type specifiers

34.36 (instance-ref CNAME SCHEMECLASS)
======================================

A reference to a C++ class instance.


File: chicken.info,  Node: Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];,  Next: Foreign type specifiers - Mappings,  Prev: Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;,  Up: Foreign type specifiers

34.37 (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
================================================================

A function pointer. `CALLCONV' specifies an optional calling convention
and should be a string. The meaning of this string is entirely platform
dependent. The value `#f' is also allowed and is passed as a `NULL'
pointer.


File: chicken.info,  Node: Foreign type specifiers - Mappings,  Prev: Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];,  Up: Foreign type specifiers

34.38 Mappings
==============

Foreign types are mapped to C types in the following manner:

   <table> <tr><td>bool</td><td> int
</td></tr><tr><td>[unsigned-]char</td><td> [unsigned] char
</td></tr><tr><td>[unsigned-]short</td><td> [unsigned] short
</td></tr><tr><td>[unsigned-]int</td><td> [unsigned] int
</td></tr><tr><td>[unsigned-]integer</td><td> [unsigned] int
</td></tr><tr><td>[unsigned-]long</td><td> [unsigned] long
</td></tr><tr><td>float</td><td> float
</td></tr><tr><td>double</td><td> double
</td></tr><tr><td>number</td><td> double
</td></tr><tr><td>[nonnull-]c-pointer</td><td> void *
</td></tr><tr><td>[nonnull-]blob</td><td> unsigned char *
</td></tr><tr><td>[nonnull-]u8vector</td><td> unsigned char *
</td></tr><tr><td>[nonnull-]s8vector</td><td> char *
</td></tr><tr><td>[nonnull-]u16vector</td><td> unsigned short *
</td></tr><tr><td>[nonnull-]s16vector</td><td> short *
</td></tr><tr><td>[nonnull-]u32vector</td><td> uint32_t *
</td></tr><tr><td>[nonnull-]s32vector</td><td> int32_t *
</td></tr><tr><td>[nonnull-]f32vector</td><td> float *
</td></tr><tr><td>[nonnull-]f64vector</td><td> double *
</td></tr><tr><td>[nonnull-]c-string</td><td> char *
</td></tr><tr><td>[nonnull-]unsigned-c-string</td><td> unsigned char *
</td></tr> <tr><td>c-string-list</td><td>char **</td></tr>
<tr><td>symbol</td><td> char * </td></tr><tr><td>void</td><td> void
</td></tr><tr><td>([nonnull-]c-pointer TYPE)</td><td> TYPE *
</td></tr><tr><td>(enum NAME)</td><td> enum NAME
</td></tr><tr><td>(struct NAME)</td><td> struct NAME
</td></tr><tr><td>(ref TYPE)</td><td> TYPE &
</td></tr><tr><td>(template T1 T2 ...)</td><td> T1<T2, ...>
</td></tr><tr><td>(union NAME)</td><td> union NAME
</td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td>
[CALLCONV] RTYPE (*)(ATYPE, ...) </td></tr><tr><td>(instance CNAME
SNAME)</td><td> CNAME * </td></tr><tr><td>(instance-ref CNAME
SNAME)</td><td> CNAME & </td></tr></table>

   Previous: *Note Accessing external objects: Accessing external
objects.

   Next: *Note Embedding: Embedding.


File: chicken.info,  Node: Embedding,  Next: Callbacks,  Prev: Foreign type specifiers,  Up: Top

35 Embedding
************

* Menu:

* Embedding - CHICKEN_parse_command_line::
* Embedding - CHICKEN_initialize::
* Embedding - CHICKEN_run::
* Embedding - return-to-host::
* Embedding - CHICKEN_eval::
* Embedding - CHICKEN_eval_string::
* Embedding - CHICKEN_eval_to_string::
* Embedding - CHICKEN_eval_string_to_string::
* Embedding - CHICKEN_apply::
* Embedding - CHICKEN_apply_to_string::
* Embedding - CHICKEN_read::
* Embedding - CHICKEN_load::
* Embedding - CHICKEN_get_error_message::
* Embedding - CHICKEN_yield::
* Embedding - CHICKEN_continue::
* Embedding - CHICKEN_new_gc_root::
* Embedding - CHICKEN_delete_gc_root::
* Embedding - CHICKEN_gc_root_ref::
* Embedding - CHICKEN_gc_root_set::
* Embedding - CHICKEN_global_lookup::
* Embedding - CHICKEN_global_ref::
* Embedding - CHICKEN_global_set::

   Compiled Scheme files can be linked with C code, provided the Scheme
code was compiled in _embedded_ mode by passing `-DC_EMBEDDED' to the C
compiler (this will disable generation of a `main()' function). `csc'
will do this, when given the `-embedded' option. Alternatively pass
`-embedded' to `csc'.

   The following C API is available:


File: chicken.info,  Node: Embedding - CHICKEN_parse_command_line,  Next: Embedding - CHICKEN_initialize,  Up: Embedding

35.1 CHICKEN_parse_command_line
===============================


[C function] void CHICKEN_parse_command_line (int argc, char *argv[], int *heap, int *stack int *symbols)
 Parse the programs command-line contained in `argc' and `argv' and
return the heap-, stack- and symbol table limits given by runtime
options of the form `-:...', or choose default limits. The library
procedure `argv' can access the command-line only if this function has
been called by the containing application.


File: chicken.info,  Node: Embedding - CHICKEN_initialize,  Next: Embedding - CHICKEN_run,  Prev: Embedding - CHICKEN_parse_command_line,  Up: Embedding

35.2 CHICKEN_initialize
=======================


[C function] int CHICKEN_initialize (int heap, int stack, int symbols, void *toplevel)
 Initializes the Scheme execution context and memory. `heap' holds the
number of bytes that are to be allocated for the secondary heap.
`stack' holds the number of bytes for the primary heap. `symbols'
contains the size of the symbol table. Passing `0' to one or more of
these parameters will select a default size.  `toplevel' should be a
pointer to the toplevel entry point procedure. You should pass
`C_toplevel' here. In any subsequent call to `CHICKEN_run' you can
simply pass `NULL'. Calling this function more than once has no effect.
If enough memory is available and initialization was successful, then
`1' is returned, otherwise this function returns `0'.


File: chicken.info,  Node: Embedding - CHICKEN_run,  Next: Embedding - return-to-host,  Prev: Embedding - CHICKEN_initialize,  Up: Embedding

35.3 CHICKEN_run
================


[C function] C_word CHICKEN_run (void *toplevel)
 Starts the Scheme program. Call this function once to execute all
toplevel expressions in your compiled Scheme program. If the runtime
system was not initialized before, then `CHICKEN_initialize' is called
with default sizes. `toplevel' is the toplevel entry-point procedure,
you usually pass `C_toplevel' here. The result value is the
continuation that can be used to re-invoke the Scheme code from the
point after it called `return-to-host' (see below).

If you just need a Scheme interpreter, you can also pass
`CHICKEN_default_toplevel' as the toplevel procedure, which just uses
the default library units.

   Once `CHICKEN_run' has been called, Scheme code is executing until
all toplevel expressions have been evaluated or until `return-to-host'
is called inside the Scheme program.


File: chicken.info,  Node: Embedding - return-to-host,  Next: Embedding - CHICKEN_eval,  Prev: Embedding - CHICKEN_run,  Up: Embedding

35.4 return-to-host
===================


[procedure] (return-to-host)
 Exits the Scheme code and returns to the invoking context that called
`CHICKEN_run' or `CHICKEN_continue'.

After `return-to-host' has been executed and once `CHICKEN_run'
returns, you can invoke callbacks which have been defined with
`define-external'. The `eval' library unit also provides _boilerplate_
callbacks, that simplify invoking Scheme code embedded in a C or C++
application a lot.


File: chicken.info,  Node: Embedding - CHICKEN_eval,  Next: Embedding - CHICKEN_eval_string,  Prev: Embedding - return-to-host,  Up: Embedding

35.5 CHICKEN_eval
=================


[C macro] int CHICKEN_eval (C_word exp, C_word *result)
 Evaluates the Scheme object passed in `exp', writing the result value
to `result'. The return value is 1 if the operation succeeded, or 0 if
an error occurred. Call `CHICKEN_get_error_message' to obtain a
description of the error.


File: chicken.info,  Node: Embedding - CHICKEN_eval_string,  Next: Embedding - CHICKEN_eval_to_string,  Prev: Embedding - CHICKEN_eval,  Up: Embedding

35.6 CHICKEN_eval_string
========================


[C macro] int CHICKEN_eval_string (char *str, C_word *result)
 Evaluates the Scheme expression passed in the string `str', writing
the result value to `result'.


File: chicken.info,  Node: Embedding - CHICKEN_eval_to_string,  Next: Embedding - CHICKEN_eval_string_to_string,  Prev: Embedding - CHICKEN_eval_string,  Up: Embedding

35.7 CHICKEN_eval_to_string
===========================


[C macro] int CHICKEN_eval_to_string (C_word exp, char *result, int size)
 Evaluates the Scheme expression passed in `exp', writing a textual
representation of the result into `result'. `size' should specify the
maximal size of the result string.


File: chicken.info,  Node: Embedding - CHICKEN_eval_string_to_string,  Next: Embedding - CHICKEN_apply,  Prev: Embedding - CHICKEN_eval_to_string,  Up: Embedding

35.8 CHICKEN_eval_string_to_string
==================================


[C macro] int CHICKEN_eval_string_to_string (char *str, char *result, int size)
 Evaluates the Scheme expression passed in the string `str', writing a
textual representation of the result into `result'. `size' should
specify the maximal size of the result string.


File: chicken.info,  Node: Embedding - CHICKEN_apply,  Next: Embedding - CHICKEN_apply_to_string,  Prev: Embedding - CHICKEN_eval_string_to_string,  Up: Embedding

35.9 CHICKEN_apply
==================


[C macro] int CHICKEN_apply (C_word func, C_word args, C_word *result)
 Applies the procedure passed in `func' to the list of arguments
`args', writing the result value to `result'.


File: chicken.info,  Node: Embedding - CHICKEN_apply_to_string,  Next: Embedding - CHICKEN_read,  Prev: Embedding - CHICKEN_apply,  Up: Embedding

35.10 CHICKEN_apply_to_string
=============================


[C macro] int CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size)
 Applies the procedure passed in `func' to the list of arguments
`args', writing a textual  representation of the result into `result'.


File: chicken.info,  Node: Embedding - CHICKEN_read,  Next: Embedding - CHICKEN_load,  Prev: Embedding - CHICKEN_apply_to_string,  Up: Embedding

35.11 CHICKEN_read
==================


[C macro] int CHICKEN_read (char *str, C_word *result)
 Reads a Scheme object from the string `str', writing the result value
to `result'.


File: chicken.info,  Node: Embedding - CHICKEN_load,  Next: Embedding - CHICKEN_get_error_message,  Prev: Embedding - CHICKEN_read,  Up: Embedding

35.12 CHICKEN_load
==================


[C macro] int CHICKEN_load (char *filename)
 Loads the Scheme file `filename' (either in source form or compiled).


File: chicken.info,  Node: Embedding - CHICKEN_get_error_message,  Next: Embedding - CHICKEN_yield,  Prev: Embedding - CHICKEN_load,  Up: Embedding

35.13 CHICKEN_get_error_message
===============================


[C macro] void CHICKEN_get_error_message (char *result, int size)
 Returns a textual description of the most recent error that occurred
in executing embedded Scheme code.


File: chicken.info,  Node: Embedding - CHICKEN_yield,  Next: Embedding - CHICKEN_continue,  Prev: Embedding - CHICKEN_get_error_message,  Up: Embedding

35.14 CHICKEN_yield
===================


[C macro] int CHICKEN_yield (int *status)
 If threads have been spawned during earlier invocations of embedded
Scheme code, then this function will run the next scheduled thread for
one complete time-slice. This is useful, for example, inside an _idle_
handler in a GUI application with background Scheme threads. Note that
the  `srfi-18' library unit has to be linked in for this.

An example:


% cat x.scm
;;; x.scm

(define (bar x) (gc) (* x x))

(define-external (baz (int i)) double
  (sqrt i))
(return-to-host)

% cat y.c
/* y.c */

#include <chicken.h>
#include <assert.h>

extern double baz(int);

int main() {
  char buffer[ 256 ];
  int status;
  C_word val = C_SCHEME_UNDEFINED;
  C_word *data[ 1 ];

  data[ 0 ] = &val;

  CHICKEN_run(C_toplevel);

  status = CHICKEN_read("(bar 99)", &val);
  assert(status);

  C_gc_protect(data, 1);

  printf("data: %08x\n", val);

  status = CHICKEN_eval_string_to_string("(bar)", buffer, 255);
  assert(!status);

  CHICKEN_get_error_message(buffer, 255);
  printf("ouch: %s\n", buffer);

  status = CHICKEN_eval_string_to_string("(bar 23)", buffer, 255);
  assert(status);

  printf("-> %s\n", buffer);
  printf("data: %08x\n", val);

  status = CHICKEN_eval_to_string(val, buffer, 255);
  assert(status);
  printf("-> %s\n", buffer);

  printf("->` %g\n", baz(22));

  return 0;
}

% csc x.scm y.c -embedded
 It is also possible to re-enter the computation following the call to
`return-to-host' by calling `CHICKEN_continue':


File: chicken.info,  Node: Embedding - CHICKEN_continue,  Next: Embedding - CHICKEN_new_gc_root,  Prev: Embedding - CHICKEN_yield,  Up: Embedding

35.15 CHICKEN_continue
======================


[C function] C_word CHICKEN_continue (C_word k)
 Re-enters Scheme execution. `k' is the continuation received from the
previous invocation of `CHICKEN_run' or `CHICKEN_continue'. When
`return-to-host' is called again, this function returns another
continuation that can be used to restart again.

If you invoke callbacks prior to calling `CHICKEN_continue', make sure
that the continuation is not reclaimed by garbage collection. This can
be avoided by using `C_gc_protect' or gc-roots.

   Another example:


% cat x.scm
(require-extension srfi-18)

(define m (make-mutex))

(define (t)
  (mutex-lock! m)
  (thread-sleep! 1)
  (print (thread-name (current-thread)))
  (mutex-unlock! m)
  (t) )

(thread-start! (make-thread t 'PING!))
(thread-start! (make-thread t 'PONG!))

(let loop ()
  (return-to-host)
  (thread-yield!)
  (loop) )

% cat y.c
#include <chicken.h>

int main()
{
  C_word k = CHICKEN_run(C_toplevel);

  for(;;)
    k = CHICKEN_continue(k);

  return 0;
}

% csc x.scm y.c -embedded
 It is advisable not to mix repeated uses of
`CHICKEN_continue'/`return-to-host' (as in the example above) with
callbacks. Once `return-to-host' is invoked, the runtime system and any
Scheme code executed prior to the invocation is initialized and can be
conveniently used via callbacks.

   A simpler interface For handling GC-safe references to Scheme data
are the so called _gc-roots_:


File: chicken.info,  Node: Embedding - CHICKEN_new_gc_root,  Next: Embedding - CHICKEN_delete_gc_root,  Prev: Embedding - CHICKEN_continue,  Up: Embedding

35.16 CHICKEN_new_gc_root
=========================


[C function] void* CHICKEN_new_gc_root ()
 Returns a pointer to a _GC root_, which is an object that holds a
reference to a Scheme value that will always be valid, even after a
garbage collection. The content of the gc root is initialized to an
unspecified value.


File: chicken.info,  Node: Embedding - CHICKEN_delete_gc_root,  Next: Embedding - CHICKEN_gc_root_ref,  Prev: Embedding - CHICKEN_new_gc_root,  Up: Embedding

35.17 CHICKEN_delete_gc_root
============================


[C function] void CHICKEN_delete_gc_root (void *root)
 Deletes the gc root.


File: chicken.info,  Node: Embedding - CHICKEN_gc_root_ref,  Next: Embedding - CHICKEN_gc_root_set,  Prev: Embedding - CHICKEN_delete_gc_root,  Up: Embedding

35.18 CHICKEN_gc_root_ref
=========================


[C macro] C_word CHICKEN_gc_root_ref (void *root)
 Returns the value stored in the gc root.


File: chicken.info,  Node: Embedding - CHICKEN_gc_root_set,  Next: Embedding - CHICKEN_global_lookup,  Prev: Embedding - CHICKEN_gc_root_ref,  Up: Embedding

35.19 CHICKEN_gc_root_set
=========================


[C macro] void CHICKEN_gc_root_set (void *root, C_word value)
 Sets the content of the GC root to a new value.

Sometimes it is handy to access global variables from C code:


File: chicken.info,  Node: Embedding - CHICKEN_global_lookup,  Next: Embedding - CHICKEN_global_ref,  Prev: Embedding - CHICKEN_gc_root_set,  Up: Embedding

35.20 CHICKEN_global_lookup
===========================


[C function] void* CHICKEN_global_lookup (char *name)
 Returns a GC root that holds the global variable with the name `name'.
If no such variable exists, `NULL' is returned.


File: chicken.info,  Node: Embedding - CHICKEN_global_ref,  Next: Embedding - CHICKEN_global_set,  Prev: Embedding - CHICKEN_global_lookup,  Up: Embedding

35.21 CHICKEN_global_ref
========================


[C function] C_word CHICKEN_global_ref (void *global)
 Returns the value of the global variable referenced by the GC root
`global'.


File: chicken.info,  Node: Embedding - CHICKEN_global_set,  Prev: Embedding - CHICKEN_global_ref,  Up: Embedding

35.22 CHICKEN_global_set
========================


[C function] void CHICKEN_global_set (void *global, C_word value)
 Sets the value of the global variable referenced by the GC root
`global' to `value'.

Previous: *Note Foreign type specifiers: Foreign type specifiers.

   Next: *Note Callbacks: Callbacks.


File: chicken.info,  Node: Callbacks,  Next: Locations,  Prev: Embedding,  Up: Top

36 Callbacks
************

* Menu:

* Callbacks - define-external::
* Callbacks - C_callback::
* Callbacks - C_callback_adjust_stack::

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

   Note: the names of all functions, variables and macros exported by
the CHICKEN runtime system start with `C_'. It is advisable to use a
different naming scheme for your own code to avoid name clashes.
Callbacks (defined by `define-external') do not capture the lexical
environment.

   Non-local exits leaving the scope of the invocation of a callback
from Scheme into C will not remove the C call-frame from the stack (and
will result in a memory leak).


File: chicken.info,  Node: Callbacks - define-external,  Next: Callbacks - C_callback,  Up: Callbacks

36.1 define-external
====================


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

     (define-external (foo (c-string x)) int (string-length x))
The second form of `define-external' can be used to define variables
that are accessible from foreign code. It declares a global variable
named by the symbol `NAME' that has the type `TYPE'. `INIT' can be an
arbitrary expression that is used to initialize the variable. `NAME' is
accessible from Scheme just like any other foreign variable defined by
`define-foreign-variable'.

     (define-external foo int 42)
     ((foreign-lambda* int ()
       *"C_return(foo);"*))           =*=>* 42
   Note: don't be tempted to assign strings or bytevectors to external
variables. Garbage collection moves those objects around, so it is very
bad idea to assign pointers to heap-data. If you have to do so, then
copy the data object into statically allocated memory (for example by
using `object-evict').

   Results of type `scheme-object' returned by `define-external' are
always allocated in the secondary heap, that is, not in the stack.


File: chicken.info,  Node: Callbacks - C_callback,  Next: Callbacks - C_callback_adjust_stack,  Prev: Callbacks - define-external,  Up: Callbacks

36.2 C_callback
===============


[C function] C_word C_callback (C_word closure, int argc)
 This function can be used to invoke the Scheme procedure `closure'.
`argc' should contain the number of arguments that are passed to the
procedure on the temporary stack. Values are put onto the temporary
stack with the `C_save' macro.


File: chicken.info,  Node: Callbacks - C_callback_adjust_stack,  Prev: Callbacks - C_callback,  Up: Callbacks

36.3 C_callback_adjust_stack
============================


[C function] void C_callback_adjust_stack (C_word *ptr, int size)
 The runtime-system uses the stack as a special allocation area and
internally holds pointers to estimated limits to distinguish between
Scheme data objects inside the stack from objects outside of it.  If
you invoke callbacks at wildly differing stack-levels, these limits may
shift from invocation to invocation. Callbacks defined with
`define-external' will perform appropriate adjustments automatically,
but if you invoke `C_callback' manually, you should perform a
`C_callback_adjust_stack' to make sure the internal limits are set
properly. `ptr' should point to some data object on the stack and
`size' is the number of words contained in the data object (or some
estimate). The call will make sure the limits are adjusted so that the
value pointed to by `ptr' is located in the stack.

Previous: *Note Embedding: Embedding.

   Next: *Note Locations: Locations.


File: chicken.info,  Node: Locations,  Next: Other support procedures,  Prev: Callbacks,  Up: Top

37 Locations
************

* Menu:

* Locations - define-location::
* Locations - let-location::
* Locations - location::

   It is also possible to define variables containing unboxed C data,
so called _locations_. It should be noted that locations may only
contain simple data, that is: everything that fits into a machine word,
and double-precision floating point values.


File: chicken.info,  Node: Locations - define-location,  Next: Locations - let-location,  Up: Locations

37.1 define-location
====================


[syntax] (define-location NAME TYPE [INIT])
 Identical to `(define-external NAME TYPE [INIT])', but the variable is
not accessible from outside of the current compilation unit (it is
declared `static').


File: chicken.info,  Node: Locations - let-location,  Next: Locations - location,  Prev: Locations - define-location,  Up: Locations

37.2 let-location
=================


[syntax] (let-location ((NAME TYPE [INIT]) ...) BODY ...)
 Defines a lexically bound location.


File: chicken.info,  Node: Locations - location,  Prev: Locations - let-location,  Up: Locations

37.3 location
=============


[syntax] (location NAME)
[syntax] (location X)
 This form returns a pointer object that contains the address of the
variable `NAME'.  If the argument to `location' is not a location
defined by `define-location', `define-external' or `let-location', then


(location X)
 is essentially equivalent to


(make-locative X)
 (See the manual chapter or `locatives' for more information about
locatives.

Note that `(location X)' may be abbreviated as `#$X'.

     (define-external foo int)
     ((foreign-lambda* void (((c-pointer int) ip)) *"*ip = 123;"*)
       (location foo))
     foo                                                                               =*=>* 123
   This facility is especially useful in situations, where a C function
returns more than one result value:

     #>
     #include <math.h>
     <#

     (*define* *modf*
       (foreign-lambda double *"modf"* double (c-pointer double)) )

     (let-location ([i double])
       (*let* ([f (modf 1.99 (location i))])
         (print *"i="* i *", f="* f) ) )
   See location and c-string*
(http://chicken.wiki.br/location-and-c-string-star)  for a tip on
returning a `c-string*' type.

   `location' returns a value of type `c-pointer', when given the name
of a callback-procedure defined with `define-external'.

   Previous: *Note Callbacks: Callbacks.

   Next: *Note Other support procedures: Other support procedures.


File: chicken.info,  Node: Other support procedures,  Next: C interface,  Prev: Locations,  Up: Top

38 Other support procedures
***************************

* Menu:

* Other support procedures - argc+argv::


File: chicken.info,  Node: Other support procedures - argc+argv,  Up: Other support procedures

38.1 argc+argv
==============


[procedure] (argc+argv)
 Returns two values: an integer and a foreign-pointer object
representing the `argc' and `argv' arguments passed to the current
process.

Previous: *Note Locations: Locations.

   Next: *Note C interface: C interface.


File: chicken.info,  Node: C interface,  Next: chicken-setup,  Prev: Other support procedures,  Up: Top

39 C interface
**************

* Menu:

* C interface - C_save::
* C interface - C_restore::
* C interface - C_fix::
* C interface - C_make_character::
* C interface - C_SCHEME_END_OF_LIST::
* C interface - C_word C_SCHEME_END_OF_FILE::
* C interface - C_word C_SCHEME_FALSE::
* C interface - C_word C_SCHEME_TRUE::
* C interface - C_string::
* C interface - C_string2::
* C interface - C_intern2::
* C interface - C_intern3::
* C interface - C_pair::
* C interface - C_flonum::
* C interface - C_int_to_num::
* C interface - C_mpointer::
* C interface - C_vector::
* C interface - C_list::
* C interface - C_alloc::
* C interface - C_SIZEOF_LIST::
* C interface - C_SIZEOF_STRING::
* C interface - C_SIZEOF_VECTOR::
* C interface - C_SIZEOF_INTERNED_SYMBOL::
* C interface - C_SIZEOF_PAIR::
* C interface - C_SIZEOF_FLONUM::
* C interface - C_SIZEOF_POINTER::
* C interface - C_SIZEOF_LOCATIVE::
* C interface - C_SIZEOF_TAGGED_POINTER::
* C interface - C_character_code::
* C interface - C_unfix::
* C interface - C_flonum_magnitude::
* C interface - C_c_string::
* C interface - C_num_to_int::
* C interface - C_pointer_address::
* C interface - C_header_size::
* C interface - C_header_bits::
* C interface - C_block_item::
* C interface - C_u_i_car::
* C interface - C_u_i_cdr::
* C interface - C_data_pointer::
* C interface - C_make_header::
* C interface - C_mutate::
* C interface - C_symbol_value::
* C interface - C_gc_protect::
* C interface - C_gc_unprotect::
* C interface - C_pre_gc_hook::
* C interface - C_post_gc_hook::
* C interface - An example for simple calls to foreign code involving callbacks::
* C interface - Notes;::

   The following functions and macros are available for C code that
invokes Scheme or foreign procedures that are called by Scheme:


File: chicken.info,  Node: C interface - C_save,  Next: C interface - C_restore,  Up: C interface

39.1 C_save
===========


[C macro] void C_save (C_word x) :
 Saves the Scheme data object `x' on the temporary stack.


File: chicken.info,  Node: C interface - C_restore,  Next: C interface - C_fix,  Prev: C interface - C_save,  Up: C interface

39.2 C_restore
==============


[C macro] void C_restore
 Pops and returns the topmost value from the temporary stack.


File: chicken.info,  Node: C interface - C_fix,  Next: C interface - C_make_character,  Prev: C interface - C_restore,  Up: C interface

39.3 C_fix
==========


[C macro] C_word C_fix (int integer)


File: chicken.info,  Node: C interface - C_make_character,  Next: C interface - C_SCHEME_END_OF_LIST,  Prev: C interface - C_fix,  Up: C interface

39.4 C_make_character
=====================


[C macro] C_word C_make_character (int char_code)


File: chicken.info,  Node: C interface - C_SCHEME_END_OF_LIST,  Next: C interface - C_word C_SCHEME_END_OF_FILE,  Prev: C interface - C_make_character,  Up: C interface

39.5 C_SCHEME_END_OF_LIST
=========================


[C macro] C_SCHEME_END_OF_LIST


File: chicken.info,  Node: C interface - C_word C_SCHEME_END_OF_FILE,  Next: C interface - C_word C_SCHEME_FALSE,  Prev: C interface - C_SCHEME_END_OF_LIST,  Up: C interface

39.6 C_word C_SCHEME_END_OF_FILE
================================


[C macro] C_SCHEME_END_OF_FILE


File: chicken.info,  Node: C interface - C_word C_SCHEME_FALSE,  Next: C interface - C_word C_SCHEME_TRUE,  Prev: C interface - C_word C_SCHEME_END_OF_FILE,  Up: C interface

39.7 C_word C_SCHEME_FALSE
==========================


[C macro] C_SCHEME_FALSE


File: chicken.info,  Node: C interface - C_word C_SCHEME_TRUE,  Next: C interface - C_string,  Prev: C interface - C_word C_SCHEME_FALSE,  Up: C interface

39.8 C_word C_SCHEME_TRUE
=========================


[C macro] C_SCHEME_TRUE
 These macros return immediate Scheme data objects.


File: chicken.info,  Node: C interface - C_string,  Next: C interface - C_string2,  Prev: C interface - C_word C_SCHEME_TRUE,  Up: C interface

39.9 C_string
=============


[C function] C_word C_string (C_word **ptr, int length, char *string)


File: chicken.info,  Node: C interface - C_string2,  Next: C interface - C_intern2,  Prev: C interface - C_string,  Up: C interface

39.10 C_string2
===============


[C function] C_word C_string2 (C_word **ptr, char *zero_terminated_string)


File: chicken.info,  Node: C interface - C_intern2,  Next: C interface - C_intern3,  Prev: C interface - C_string2,  Up: C interface

39.11 C_intern2
===============


[C function] C_word C_intern2 (C_word **ptr, char *zero_terminated_string)


File: chicken.info,  Node: C interface - C_intern3,  Next: C interface - C_pair,  Prev: C interface - C_intern2,  Up: C interface

39.12 C_intern3
===============


[C function] C_word C_intern3 (C_word **ptr, char *zero_terminated_string, C_word initial_value)


File: chicken.info,  Node: C interface - C_pair,  Next: C interface - C_flonum,  Prev: C interface - C_intern3,  Up: C interface

39.13 C_pair
============


[C function] C_word C_pair (C_word **ptr, C_word car, C_word cdr)


File: chicken.info,  Node: C interface - C_flonum,  Next: C interface - C_int_to_num,  Prev: C interface - C_pair,  Up: C interface

39.14 C_flonum
==============


[C function] C_word C_flonum (C_word **ptr, double number)


File: chicken.info,  Node: C interface - C_int_to_num,  Next: C interface - C_mpointer,  Prev: C interface - C_flonum,  Up: C interface

39.15 C_int_to_num
==================


[C function] C_word C_int_to_num (C_word **ptr, int integer)


File: chicken.info,  Node: C interface - C_mpointer,  Next: C interface - C_vector,  Prev: C interface - C_int_to_num,  Up: C interface

39.16 C_mpointer
================


[C function] C_word C_mpointer (C_word **ptr, void *pointer)


File: chicken.info,  Node: C interface - C_vector,  Next: C interface - C_list,  Prev: C interface - C_mpointer,  Up: C interface

39.17 C_vector
==============


[C function] C_word C_vector (C_word **ptr, int length, ...)


File: chicken.info,  Node: C interface - C_list,  Next: C interface - C_alloc,  Prev: C interface - C_vector,  Up: C interface

39.18 C_list
============


[C function] C_word C_list (C_word **ptr, int length, ...)
 These functions allocate memory from `ptr' and initialize a fresh data
object. The new data object is returned. `ptr' should be the address of
an allocation pointer created with `C_alloc'.


File: chicken.info,  Node: C interface - C_alloc,  Next: C interface - C_SIZEOF_LIST,  Prev: C interface - C_list,  Up: C interface

39.19 C_alloc
=============


[C macro] C_word* C_alloc (int words)
 Allocates memory from the C stack (`C_alloc') and returns a pointer to
it. `words' should be the number of words needed for all data objects
that are to be created in this function.  Note that stack-allocated
data objects have to be passed to Scheme callback functions, or they
will not be seen by the garbage collector. This is really only usable
for callback procedure invocations, make sure not to use it in normal
code, because the allocated memory will be re-used after the foreign
procedure returns. When invoking Scheme callback procedures a minor
garbage collection is performed, so data allocated with `C_alloc' will
already have moved to a safe place.

Note that `C_alloc' is really just a wrapper around `alloca', and can
also be simulated by declaring a stack-allocated array of `C_word's:


File: chicken.info,  Node: C interface - C_SIZEOF_LIST,  Next: C interface - C_SIZEOF_STRING,  Prev: C interface - C_alloc,  Up: C interface

39.20 C_SIZEOF_LIST
===================


[C macro] int C_SIZEOF_LIST (int length)


File: chicken.info,  Node: C interface - C_SIZEOF_STRING,  Next: C interface - C_SIZEOF_VECTOR,  Prev: C interface - C_SIZEOF_LIST,  Up: C interface

39.21 C_SIZEOF_STRING
=====================


[C macro] int C_SIZEOF_STRING (int length)


File: chicken.info,  Node: C interface - C_SIZEOF_VECTOR,  Next: C interface - C_SIZEOF_INTERNED_SYMBOL,  Prev: C interface - C_SIZEOF_STRING,  Up: C interface

39.22 C_SIZEOF_VECTOR
=====================


[C macro] int C_SIZEOF_VECTOR (int length)


File: chicken.info,  Node: C interface - C_SIZEOF_INTERNED_SYMBOL,  Next: C interface - C_SIZEOF_PAIR,  Prev: C interface - C_SIZEOF_VECTOR,  Up: C interface

39.23 C_SIZEOF_INTERNED_SYMBOL
==============================


[C macro] int C_SIZEOF_INTERNED_SYMBOL (int length)


File: chicken.info,  Node: C interface - C_SIZEOF_PAIR,  Next: C interface - C_SIZEOF_FLONUM,  Prev: C interface - C_SIZEOF_INTERNED_SYMBOL,  Up: C interface

39.24 C_SIZEOF_PAIR
===================


[C macro] int C_SIZEOF_PAIR


File: chicken.info,  Node: C interface - C_SIZEOF_FLONUM,  Next: C interface - C_SIZEOF_POINTER,  Prev: C interface - C_SIZEOF_PAIR,  Up: C interface

39.25 C_SIZEOF_FLONUM
=====================


[C macro] int C_SIZEOF_FLONUM


File: chicken.info,  Node: C interface - C_SIZEOF_POINTER,  Next: C interface - C_SIZEOF_LOCATIVE,  Prev: C interface - C_SIZEOF_FLONUM,  Up: C interface

39.26 C_SIZEOF_POINTER
======================


[C macro] int C_SIZEOF_POINTER


File: chicken.info,  Node: C interface - C_SIZEOF_LOCATIVE,  Next: C interface - C_SIZEOF_TAGGED_POINTER,  Prev: C interface - C_SIZEOF_POINTER,  Up: C interface

39.27 C_SIZEOF_LOCATIVE
=======================


[C macro] int C_SIZEOF_LOCATIVE


File: chicken.info,  Node: C interface - C_SIZEOF_TAGGED_POINTER,  Next: C interface - C_character_code,  Prev: C interface - C_SIZEOF_LOCATIVE,  Up: C interface

39.28 C_SIZEOF_TAGGED_POINTER
=============================


[C macro] int C_SIZEOF_TAGGED_POINTER
 These are macros that return the size in words needed for a data
object of a given type.


File: chicken.info,  Node: C interface - C_character_code,  Next: C interface - C_unfix,  Prev: C interface - C_SIZEOF_TAGGED_POINTER,  Up: C interface

39.29 C_character_code
======================


[C macro] int C_character_code (C_word character)


File: chicken.info,  Node: C interface - C_unfix,  Next: C interface - C_flonum_magnitude,  Prev: C interface - C_character_code,  Up: C interface

39.30 C_unfix
=============


[C macro] int C_unfix (C_word fixnum)


File: chicken.info,  Node: C interface - C_flonum_magnitude,  Next: C interface - C_c_string,  Prev: C interface - C_unfix,  Up: C interface

39.31 C_flonum_magnitude
========================


[C macro] double C_flonum_magnitude (C_word flonum)


File: chicken.info,  Node: C interface - C_c_string,  Next: C interface - C_num_to_int,  Prev: C interface - C_flonum_magnitude,  Up: C interface

39.32 C_c_string
================


[C function] char* C_c_string (C_word string)


File: chicken.info,  Node: C interface - C_num_to_int,  Next: C interface - C_pointer_address,  Prev: C interface - C_c_string,  Up: C interface

39.33 C_num_to_int
==================


[C function] int C_num_to_int (C_word fixnum_or_flonum)


File: chicken.info,  Node: C interface - C_pointer_address,  Next: C interface - C_header_size,  Prev: C interface - C_num_to_int,  Up: C interface

39.34 C_pointer_address
=======================


[C function] void* C_pointer_address (C_word pointer)
 These macros and functions can be used to convert Scheme data objects
back to C data. Note that `C_c_string()' returns a pointer to the
character buffer of the actual Scheme object and is not zero-terminated.


File: chicken.info,  Node: C interface - C_header_size,  Next: C interface - C_header_bits,  Prev: C interface - C_pointer_address,  Up: C interface

39.35 C_header_size
===================


[C macro] int C_header_size (C_word x)


File: chicken.info,  Node: C interface - C_header_bits,  Next: C interface - C_block_item,  Prev: C interface - C_header_size,  Up: C interface

39.36 C_header_bits
===================


[C macro] int C_header_bits (C_word x)
 Return the number of elements and the type-bits of the non-immediate
Scheme data object `x'.


File: chicken.info,  Node: C interface - C_block_item,  Next: C interface - C_u_i_car,  Prev: C interface - C_header_bits,  Up: C interface

39.37 C_block_item
==================


[C macro] C_word C_block_item (C_word x, int index)
 This macro can be used to access slots of the non-immediate Scheme
data object `x'.  `index' specifies the index of the slot to be
fetched, starting at 0. Pairs have 2 slots, one for the car and one for
the cdr. Vectors have one slot for each element.


File: chicken.info,  Node: C interface - C_u_i_car,  Next: C interface - C_u_i_cdr,  Prev: C interface - C_block_item,  Up: C interface

39.38 C_u_i_car
===============


[C macro] C_word C_u_i_car (C_word x)


File: chicken.info,  Node: C interface - C_u_i_cdr,  Next: C interface - C_data_pointer,  Prev: C interface - C_u_i_car,  Up: C interface

39.39 C_u_i_cdr
===============


[C macro] C_word C_u_i_cdr (C_word x)
 Aliases for `C_block_item(x, 0)' and `C_block_item(x, 1)',
respectively.


File: chicken.info,  Node: C interface - C_data_pointer,  Next: C interface - C_make_header,  Prev: C interface - C_u_i_cdr,  Up: C interface

39.40 C_data_pointer
====================


[C macro] void* C_data_pointer (C_word x)
 Returns a pointer to the data-section of a non-immediate Scheme object.


File: chicken.info,  Node: C interface - C_make_header,  Next: C interface - C_mutate,  Prev: C interface - C_data_pointer,  Up: C interface

39.41 C_make_header
===================


[C macro] C_word C_make_header (C_word bits, C_word size)
 A macro to build a Scheme object header from its bits and size parts.


File: chicken.info,  Node: C interface - C_mutate,  Next: C interface - C_symbol_value,  Prev: C interface - C_make_header,  Up: C interface

39.42 C_mutate
==============


[C function] C_word C_mutate (C_word *slot, C_word val)
 Assign the Scheme value `val' to the location specified by `slot'.  If
the value points to data inside the nursery (the first
heap-generation), then the garbage collector will remember to handle
the data appropriately. Assigning nursery-pointers directly will
otherwise result in lost data. Note that no copying takes place at the
moment when `C_mutate' is called, but later - at the next (minor)
garbage collection.


File: chicken.info,  Node: C interface - C_symbol_value,  Next: C interface - C_gc_protect,  Prev: C interface - C_mutate,  Up: C interface

39.43 C_symbol_value
====================


[C macro] C_word C_symbol_value (C_word symbol)
 Returns the global value of the variable with the name `symbol'. If
the variable is unbound `C_SCHEME_UNBOUND' is returned. You can set a
variable's value with `C_mutate(&C_symbol_value(SYMBOL), VALUE)'.


File: chicken.info,  Node: C interface - C_gc_protect,  Next: C interface - C_gc_unprotect,  Prev: C interface - C_symbol_value,  Up: C interface

39.44 C_gc_protect
==================


[C function] void C_gc_protect (C_word *ptrs[], int n)
 Registers `n' variables at address `ptrs' to be garbage collection
roots. The locations should not contain pointers to data allocated in
the nursery, only immediate values or pointers to heap-data are valid.
Any assignment of potential nursery data into a root-array should be
done via `C_mutate()'. The variables have to be initialized to sensible
values before the next garbage collection starts (when in doubt, set
all locations in `ptrs' to `C_SCHEME_UNDEFINED') `C_gc_protect' may not
called before the runtime system has been initialized (either by
`CHICKEN_initialize', `CHICKEN_run' or `CHICKEN_invoke'.

For a slightly simpler interface to creating and using GC roots see
`CHICKEN_new_gc_root'.


File: chicken.info,  Node: C interface - C_gc_unprotect,  Next: C interface - C_pre_gc_hook,  Prev: C interface - C_gc_protect,  Up: C interface

39.45 C_gc_unprotect
====================


[C function] void C_gc_unprotect (int n)
 Removes the last `n' registered variables from the set of root
variables.


File: chicken.info,  Node: C interface - C_pre_gc_hook,  Next: C interface - C_post_gc_hook,  Prev: C interface - C_gc_unprotect,  Up: C interface

39.46 C_pre_gc_hook
===================


[C Variable] void (*C_pre_gc_hook)(int mode)
 If not `NULL', the function pointed to by this variable will be called
before each garbage collection with a flag indicating what kind of
collection was performed (either `0' for a minor collection or `2' for
a resizing collection). A "resizing" collection means a secondary
collection that moves all live data into a enlarged (or shrinked)
heap-space. Minor collections happen very frequently, so the hook
function should not consume too much time. The hook function may not
invoke Scheme callbacks.

Note that resizing collections may be nested in normal major
collections.


File: chicken.info,  Node: C interface - C_post_gc_hook,  Next: C interface - An example for simple calls to foreign code involving callbacks,  Prev: C interface - C_pre_gc_hook,  Up: C interface

39.47 C_post_gc_hook
====================


[C Variable] void (*C_post_gc_hook)(int mode, long ms)
 If not `NULL', the function pointed to by this variable will be called
after each garbage collection with a flag indicating what kind of
collection was performed (either `0' for a minor collection, `1' for a
major collection or `2' for a resizing collection). Minor collections
happen very frequently, so the hook function should not consume too
much time. The hook function may not invoke Scheme callbacks. The `ms'
argument records the number of milliseconds required for the garbage
collection, if the collection was a major one. For minor collections
the value of the `ms' argument is undefined.


File: chicken.info,  Node: C interface - An example for simple calls to foreign code involving callbacks,  Next: C interface - Notes;,  Prev: C interface - C_post_gc_hook,  Up: C interface

39.48 An example for simple calls to foreign code involving callbacks
=====================================================================


% cat foo.scm
#>
extern int callout(int, int, int);
<#

(define callout (foreign-safe-lambda int "callout" int int int))

(define-external (callin (scheme-object xyz)) int
  (print "This is 'callin': " xyz)
  123)

(print (callout 1 2 3))

% cat bar.c
#include <stdio.h>
#include "chicken.h"

extern int callout(int, int, int);
extern int callin(C_word x);

int callout(int x, int y, int z)
{
  C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
  C_word lst;

  printf("This is 'callout': %d, %d, %d\n", x, y, z);
  lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
  return callin(lst);  /* Note: `callin' will have GC'd the data in `ptr' */
}

% csc foo.scm bar.c -o foo
% foo
This is 'callout': 1, 2, 3
This is 'callin': (1 2 3)
123


File: chicken.info,  Node: C interface - Notes;,  Prev: C interface - An example for simple calls to foreign code involving callbacks,  Up: C interface

39.49 Notes:
============

Scheme procedures can call C functions, and C functions can call Scheme
procedures, but for every pending C stack frame, the available size of
the first heap generation (the _nursery_) will be decreased, because
the C stack is identical to the nursery. On systems with a small
nursery this might result in thrashing, since the C code between the
invocation of C from Scheme and the actual calling back to Scheme might
build up several stack-frames or allocates large amounts of stack data.
To prevent this it is advisable to increase the default nursery size,
either when compiling the file (using the `-nursery' option) or when
running the executable (using the `-:s' runtime option).

   Calls to Scheme/C may be nested arbitrarily, and Scheme
continuations can be invoked as usual, but keep in mind that C stack
frames will not be recovered, when a Scheme procedure call from C does
not return normally.

   When multiple threads are running concurrently, and control switches
from one thread to another, then the continuation of the current thread
is captured and saved. Any pending C stack frame still active from a
callback will remain on the stack until the threads is re-activated
again. This means that in a multithreading situation, when C callbacks
are involved, the available nursery space can be smaller than expected.
So doing many nested Scheme->C->Scheme calls can reduce the available
memory up to the point of thrashing. It is advisable to have only a
single thread with pending C stack-frames at any given time.

   Pointers to Scheme data objects should not be stored in local or
global variables while calling back to Scheme.  Any Scheme object not
passed back to Scheme will be reclaimed or moved by the garbage
collector.

   Calls from C to Scheme are never tail-recursive.

   Continuations captured via `call-with-current-continuation' and
passed to C code can be invoked like any other Scheme procedure.

   Previous: *Note Other support procedures: Other support procedures.

   Next: *Note chicken-setup: chicken-setup.


File: chicken.info,  Node: chicken-setup,  Next: Data representation,  Prev: C interface,  Up: Top

40 chicken-setup
****************

* Menu:

* chicken-setup - Extension libraries::
* chicken-setup - Installing extensions::
* chicken-setup - Creating extensions::
* chicken-setup - Procedures and macros available in setup scripts::
* chicken-setup - Examples for extensions::
* chicken-setup - chicken-setup reference::
* chicken-setup - Windows notes::
* chicken-setup - Security::
* chicken-setup - Other modes of installation::
* chicken-setup - Linking extensions statically::


File: chicken.info,  Node: chicken-setup - Extension libraries,  Next: chicken-setup - Installing extensions,  Up: chicken-setup

40.1 Extension libraries
========================

Extension libraries (_eggs_) are extensions to the core functionality
provided by the basic CHICKEN system, to be built and installed
separately.  The mechanism for loading compiled extensions is based on
dynamically loadable code and as such is only available on systems on
which loading compiled code at runtime is supported. Currently these
are most UNIX-compatible platforms that provide the `libdl'
functionality like Linux, Solaris, BSD, Mac OS X and Windows using
Cygwin.

   Note: Extension may also be normal applications or shell scripts,
but are usually libraries.

   `chicken-setup' will download the source code for extension
automatically from the canonical server at
http://www.call-with-current-continuation.org/eggs
(http://www.call-with-current-continuation.org/eggs) if the requested
egg does not exist in the current directory. Various command-line
options exist for customizing the process and/or retrieving the egg
from other locations or in other formats.


File: chicken.info,  Node: chicken-setup - Installing extensions,  Next: chicken-setup - Creating extensions,  Prev: chicken-setup - Extension libraries,  Up: chicken-setup

40.2 Installing extensions
==========================

* Menu:

* chicken-setup - Installing extensions - Installing extensions that use libraries::

   To install an extension library, run the `chicken-setup' program
with the extension name as argument. The extension archive is
downloaded, its contents extracted and the contained _setup_ script is
executed. This setup script is a normal Scheme source file, which will
be interpreted by `chicken-setup'. The complete language supported by
`csi' is available, and the library units `srfi-1 regex utils posix
tcp' are loaded. Additional libraries can be loaded at run-time.

   The setup script should perform all necessary steps to build the new
library (or application). After a successful build, the extension can
be installed by invoking one of the procedures `install-extension',
`install-program' or `install-script'.  These procedures will copy a
number of given files into the extension repository or in the path
where the CHICKEN executables are located (in the case of executable
programs or scripts). Additionally the list of installed files, and
user-defined metadata is stored in the repository.

   If no extension name is given on the command-line, and if none of
the options `-list', `-version', `-repository' (without argument),
`-program-path' (without argument), `-fetch', `-fetch-tree' or
`-docindex' is given, then all `.setup' scripts in the current
directory are processed.


File: chicken.info,  Node: chicken-setup - Installing extensions - Installing extensions that use libraries,  Up: chicken-setup - Installing extensions

40.2.1 Installing extensions that use libraries
-----------------------------------------------

Sometimes an extension requires a C library to compile. Compilation can
fail when your system has this library in a nonstandard location.
Luckily, normally Chicken searches in the default locations `/usr' and
`/usr/local', and in the prefix where Chicken itself was installed.
Sometimes this is not enough, so you'll need to supply chicken-setup
with some extra hints to the C compiler/linker. Here's an example:


 chicken-setup -c '-I/usr/pkg/include/mysql' -c '-L/usr/pkg/lib/mysql' -c '-L -R/usr/pkg/lib/mysql' mysql
 This installs the mysql egg with the extra compiler options -I and -L
to set the include path and the library search path. The second -L
switch passes the -R option directly to the linker, which causes the
library path to get hardcoded into the resulting extension file (for
systems that do not use ld.so.conf).


File: chicken.info,  Node: chicken-setup - Creating extensions,  Next: chicken-setup - Procedures and macros available in setup scripts,  Prev: chicken-setup - Installing extensions,  Up: chicken-setup

40.3 Creating extensions
========================

Extensions can be created by creating an (optionally gzipped) `tar'
archive named `EXTENSION.egg' containing all needed files plus a
`.setup' script in the root directory.  After `chicken-setup' has
extracted the files, the setup script will be invoked. There are no
additional constraints on the structure of the archive, but the setup
script has to be in the root path of the archive.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts,  Next: chicken-setup - Examples for extensions,  Prev: chicken-setup - Creating extensions,  Up: chicken-setup

40.4 Procedures and macros available in setup scripts
=====================================================

* Menu:

* chicken-setup - Procedures and macros available in setup scripts - install-extension::
* chicken-setup - Procedures and macros available in setup scripts - install-program::
* chicken-setup - Procedures and macros available in setup scripts - install-script::
* chicken-setup - Procedures and macros available in setup scripts - run::
* chicken-setup - Procedures and macros available in setup scripts - compile::
* chicken-setup - Procedures and macros available in setup scripts - make::
* chicken-setup - Procedures and macros available in setup scripts - patch::
* chicken-setup - Procedures and macros available in setup scripts - copy-file::
* chicken-setup - Procedures and macros available in setup scripts - move-file::
* chicken-setup - Procedures and macros available in setup scripts - remove-file*::
* chicken-setup - Procedures and macros available in setup scripts - find-library::
* chicken-setup - Procedures and macros available in setup scripts - find-header::
* chicken-setup - Procedures and macros available in setup scripts - try-compile::
* chicken-setup - Procedures and macros available in setup scripts - create-directory::
* chicken-setup - Procedures and macros available in setup scripts - chicken-prefix::
* chicken-setup - Procedures and macros available in setup scripts - installation-prefix::
* chicken-setup - Procedures and macros available in setup scripts - program-path::
* chicken-setup - Procedures and macros available in setup scripts - setup-root-directory::
* chicken-setup - Procedures and macros available in setup scripts - setup-build-directory::
* chicken-setup - Procedures and macros available in setup scripts - setup-verbose-flag::
* chicken-setup - Procedures and macros available in setup scripts - setup-install-flag::
* chicken-setup - Procedures and macros available in setup scripts - required-chicken-version::
* chicken-setup - Procedures and macros available in setup scripts - required-extension-version::
* chicken-setup - Procedures and macros available in setup scripts - cross-chicken::
* chicken-setup - Procedures and macros available in setup scripts - host-extension::


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension,  Next: chicken-setup - Procedures and macros available in setup scripts - install-program,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.1 install-extension
------------------------

* Menu:

* chicken-setup - Procedures and macros available in setup scripts - install-extension - syntax::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - version::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - documentation::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - examples::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - exports::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - static::
* chicken-setup - Procedures and macros available in setup scripts - install-extension - static-options::


(install-extension ID FILELIST [INFOLIST])
 Installs the extension library with the name `ID'. All files given in
the list of strings `FILELIST' will be copied to the extension
repository. It should be noted here that the extension id has to be
identical to the name of the file implementing the extension. The
extension may load or include other files, or may load other extensions
at runtime specified by the `require-at-runtime' property.

   `FILELIST' may be a filename, a list of filenames, or a list of
pairs of the form `(SOURCE DEST)' (if you want to copy into a
particular sub-directory - the destination directory will be created as
needed). If `DEST' is a relative pathname, < it will be copied into the
extension repository.

   The optional argument `INFOLIST' should be an association list that
maps symbols to values, this list will be stored as `ID.setup-info' at
the same location as the extension code. Currently the following
properties are used:


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - syntax,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.1 syntax
...............


[extension property] (syntax)
 Marks the extension as syntax-only. No code is compiled, the extension
is intended as a file containing macros to be loaded at
compile/macro-expansion time.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - version,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - syntax,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.2 require-at-runtime
...........................


[extension property] (require-at-runtime ID ...)
 Specifies extensions that should be loaded (via `require') at runtime.
This is mostly useful for syntax extensions that need additional
support code at runtime.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - version,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - documentation,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.3 version
................


[extension property] (version STRING)
 Specifies version string.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - documentation,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - examples,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - version,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.4 documentation
......................


[extension property] (documentation FILENAME)
 The filename of a HTML document containing extension-specific
documentation. This file should be given in the file-list passed to
`install-extension' and a link to it will be automatically included in
the index page (accessible via `chicken-setup -docindex').


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - examples,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - exports,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - documentation,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.5 examples
.................


[extension property] (examples FILENAME ...)
 Copies the given files into the examples directory, which is usually
`$prefix/share/chicken/examples' or `(make-pathname (chicken-home)
"examples")').

Note that the files listed in this property should not be listed in the
normal list of files to install passed to `install-extension'. This is
the only exception - other files that are installed in the repository
must be given in the file list.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - exports,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - static,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - examples,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.6 exports
................


[extension property] (exports EXPORT ...)
 Add export-information to the generated extension-information.
`EXPORT' may be a symbol naming an exported toplevel variable or a
string designating a file with exported variables, as generated by the
`-emit-exports' option or the `emit-exports' declaration specifier.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - static,  Next: chicken-setup - Procedures and macros available in setup scripts - install-extension - static-options,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - exports,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.7 static
...............


[extension property] (static STRING)
 If the extension also provides a static library, then STRING should
contain the name of that library. Used by `csc' when compiling with the
`-static-extensions' option.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - static-options,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension - static,  Up: chicken-setup - Procedures and macros available in setup scripts - install-extension

40.4.1.8 static-options
.......................


[extension property] (static-options STRING)
 Additional options that should be passed to the linker when linking
with the static version of an extension (see `static' above). Used by
`csc' when compiling with the `-static-extensions' option.

All other properties are currently ignored. The `FILELIST' argument may
also be a single string.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-program,  Next: chicken-setup - Procedures and macros available in setup scripts - install-script,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-extension,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.2 install-program
----------------------


[procedure] (install-program ID FILELIST [INFOLIST])
 Similar to `install-extension', but installs an executable program in
the executable path (usually `/usr/local/bin').


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - install-script,  Next: chicken-setup - Procedures and macros available in setup scripts - run,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-program,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.3 install-script
---------------------


[procedure] (install-script ID FILELIST [INFOLIST])
 Similar to `install-program', but additionally changes the file
permissions of all files in `FILELIST' to executable (for installing
shell-scripts).


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - run,  Next: chicken-setup - Procedures and macros available in setup scripts - compile,  Prev: chicken-setup - Procedures and macros available in setup scripts - install-script,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.4 run
----------


[syntax] (run FORM ...)
 Runs the shell command `FORM', which is wrapped in an implicit
`quasiquote'.  `(run (csc ...))' is treated specially and passes `-v'
(if `-verbose' has been given to `chicken-setup') and `-feature
compiling-extension' options to the compiler.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - compile,  Next: chicken-setup - Procedures and macros available in setup scripts - make,  Prev: chicken-setup - Procedures and macros available in setup scripts - run,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.5 compile
--------------


[syntax] (compile FORM ...)
 Equivalent to `(run (csc FORM ...))'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - make,  Next: chicken-setup - Procedures and macros available in setup scripts - patch,  Prev: chicken-setup - Procedures and macros available in setup scripts - compile,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.6 make
-----------


[syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)
 A _make_ macro that executes the expressions `COMMAND ...', when any
of the dependents `DEPENDENT ...' have changed, to build `TARGET'. This
is the same as the `make' extension, which is available separately. For
more information, see make
(http://www.call-with-current-continuation.org/eggs/make.html).


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - patch,  Next: chicken-setup - Procedures and macros available in setup scripts - copy-file,  Prev: chicken-setup - Procedures and macros available in setup scripts - make,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.7 patch
------------


[procedure] (patch WHICH REGEX SUBST)
 Replaces all occurrences of the regular expression `REGEX' with the
string `SUBST', in the file given in `WHICH'. If `WHICH' is a string,
the file will be patched and overwritten. If `WHICH' is a list of the
form `OLD NEW', then a different file named `NEW' will be generated.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - copy-file,  Next: chicken-setup - Procedures and macros available in setup scripts - move-file,  Prev: chicken-setup - Procedures and macros available in setup scripts - patch,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.8 copy-file
----------------


[procedure] (copy-file FROM TO)
 Copies the file or directory (recursively) given in the string `FROM'
to the destination file or directory `TO'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - move-file,  Next: chicken-setup - Procedures and macros available in setup scripts - remove-file*,  Prev: chicken-setup - Procedures and macros available in setup scripts - copy-file,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.9 move-file
----------------


[procedure] (move-file FROM TO)
 Moves the file or directory (recursively) given in the string `FROM'
to the destination file or directory `TO'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - remove-file*,  Next: chicken-setup - Procedures and macros available in setup scripts - find-library,  Prev: chicken-setup - Procedures and macros available in setup scripts - move-file,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.10 remove-file*
--------------------


[procedure] (remove-file* PATH)
 Removes the file or directory given in the string `PATH'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - find-library,  Next: chicken-setup - Procedures and macros available in setup scripts - find-header,  Prev: chicken-setup - Procedures and macros available in setup scripts - remove-file*,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.11 find-library
--------------------


[procedure] (find-library NAME PROC)
 Returns `#t' if the library named `libNAME.[a|so]' (unix) or
`NAME.lib' (windows) could be found by compiling and linking a test
program. `PROC' should be the name of a C function that must be
provided by the library. If no such library was found or the function
could not be resolved, `#f' is returned.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - find-header,  Next: chicken-setup - Procedures and macros available in setup scripts - try-compile,  Prev: chicken-setup - Procedures and macros available in setup scripts - find-library,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.12 find-header
-------------------


[procedure] (find-header NAME)
 Returns `#t' if a C include-file with the given name is available, or
`#f' otherwise.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - try-compile,  Next: chicken-setup - Procedures and macros available in setup scripts - create-directory,  Prev: chicken-setup - Procedures and macros available in setup scripts - find-header,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.13 try-compile
-------------------


[procedure] (try-compile CODE #!key cc cflags ldflags compile-only c++)
 Returns `#t' if the C code in `CODE' compiles and links successfully,
or `#f' otherwise. The keyword parameters `cc' (compiler name, defaults
to the C compiler used to build this system), `cflags' and `ldflags'
accept additional compilation and linking options. If `compile-only' is
true, then no linking step takes place. If the keyword argument `c++'
is given and true, then the code will be compiled in C++ mode.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - create-directory,  Next: chicken-setup - Procedures and macros available in setup scripts - chicken-prefix,  Prev: chicken-setup - Procedures and macros available in setup scripts - try-compile,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.14 create-directory
------------------------


[procedure] (create-directory PATH)
 Creates the directory given in the string `PATH', with all parent
directories as needed.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - chicken-prefix,  Next: chicken-setup - Procedures and macros available in setup scripts - installation-prefix,  Prev: chicken-setup - Procedures and macros available in setup scripts - create-directory,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.15 chicken-prefix
----------------------


[parameter] chicken-prefix
 The installation prefix specified when CHICKEN was built.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - installation-prefix,  Next: chicken-setup - Procedures and macros available in setup scripts - program-path,  Prev: chicken-setup - Procedures and macros available in setup scripts - chicken-prefix,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.16 installation-prefix
---------------------------


[parameter] installation-prefix
 An alternative installation prefix that will be prepended to extension
installation paths if specified. It is set by the `-install-prefix'
option or environment variable `CHICKEN_INSTALL_PREFIX'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - program-path,  Next: chicken-setup - Procedures and macros available in setup scripts - setup-root-directory,  Prev: chicken-setup - Procedures and macros available in setup scripts - installation-prefix,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.17 program-path
--------------------


[parameter] (program-path [PATH])
 Holds the path where executables are installed and defaults to either
`$CHICKEN_PREFIX/bin', if the environment variable `CHICKEN_PREFIX' is
set or the path where the CHICKEN binaries (`chicken', `csi', etc.) are
installed.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - setup-root-directory,  Next: chicken-setup - Procedures and macros available in setup scripts - setup-build-directory,  Prev: chicken-setup - Procedures and macros available in setup scripts - program-path,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.18 setup-root-directory
----------------------------


[parameter] (setup-root-directory [PATH])
 Contains the path of the directory where `chicken-setup' was invoked.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - setup-build-directory,  Next: chicken-setup - Procedures and macros available in setup scripts - setup-verbose-flag,  Prev: chicken-setup - Procedures and macros available in setup scripts - setup-root-directory,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.19 setup-build-directory
-----------------------------


[parameter] (setup-build-directory [PATH])
 Contains the path of the directory where the extension is built. This
is not necessarily identical to `setup-root-directory'.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - setup-verbose-flag,  Next: chicken-setup - Procedures and macros available in setup scripts - setup-install-flag,  Prev: chicken-setup - Procedures and macros available in setup scripts - setup-build-directory,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.20 setup-verbose-flag
--------------------------


[parameter] (setup-verbose-flag [BOOL])
 Reflects the setting of the `-verbose' option, i.e. is `#t', if
`-verbose' was given.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - setup-install-flag,  Next: chicken-setup - Procedures and macros available in setup scripts - required-chicken-version,  Prev: chicken-setup - Procedures and macros available in setup scripts - setup-verbose-flag,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.21 setup-install-flag
--------------------------


[parameter] (setup-install-flag [BOOL])
 Reflects the setting of the `--no-install' option, i.e. is `#f', if
`-no-install' was given.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - required-chicken-version,  Next: chicken-setup - Procedures and macros available in setup scripts - required-extension-version,  Prev: chicken-setup - Procedures and macros available in setup scripts - setup-install-flag,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.22 required-chicken-version
--------------------------------


[procedure] (required-chicken-version VERSION)
 Signals an error if the version of CHICKEN that this script runs under
is lexicographically less than `VERSION' (the argument will be
converted to a string, first).


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - required-extension-version,  Next: chicken-setup - Procedures and macros available in setup scripts - cross-chicken,  Prev: chicken-setup - Procedures and macros available in setup scripts - required-chicken-version,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.23 required-extension-version
----------------------------------


[procedure] (required-extension-version EXTENSION1 VERSION1 ...)
 Checks whether the extensions `EXTENSION1 ...' are installed and at
least of version `VERSION1 ...'. The test is made by lexicographically
comparing the string-representations of the given version with the
version  of the installed extension. If one of the listed extensions is
not installed, has no associated version information or is of a version
older than the one specified.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - cross-chicken,  Next: chicken-setup - Procedures and macros available in setup scripts - host-extension,  Prev: chicken-setup - Procedures and macros available in setup scripts - required-extension-version,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.24 cross-chicken
---------------------


[procedure] (cross-chicken)
 Returns `#t' if this system is configured for cross-compilation or
`#f' otherwise.


File: chicken.info,  Node: chicken-setup - Procedures and macros available in setup scripts - host-extension,  Prev: chicken-setup - Procedures and macros available in setup scripts - cross-chicken,  Up: chicken-setup - Procedures and macros available in setup scripts

40.4.25 host-extension
----------------------


[parameter] host-extension
 For a cross-compiling CHICKEN, when compiling an extension, then it
should be built for the host environment (as opposed to the target
environment). This parameter is controlled by the `-host-extension'
command-line option. A setup script should perform the proper steps of
compiling any code by passing `-host' when invoking `csc' or using the
`compile' macro.


File: chicken.info,  Node: chicken-setup - Examples for extensions,  Next: chicken-setup - chicken-setup reference,  Prev: chicken-setup - Procedures and macros available in setup scripts,  Up: chicken-setup

40.5 Examples for extensions
============================

The simplest case is a single file that does not export any syntax. For
example

     _;;;; hello.scm
     _
     (*define* (*hello* name)
       (print *"Hello, "* name *" !"*) )
   We need a `.setup' script to build and install our nifty extension:

     _;;;; hello.setup
     _
     _;; compile the code into a dynamically loadable shared object
     __;; (will generate hello.so)
     _(compile -s hello.scm)

     _;; Install as extension library
     _(install-extension 'hello *"hello.so"*)
   After entering


$ chicken-setup hello
 at the shell prompt (and in the same directory where the two files
exist), the file `hello.scm' will be compiled into a dynamically
loadable library. If the compilation succeeds, `hello.so' will be
stored in the repository, together with a file named `hello.setup-info'
containing an a-list with metadata. If no extension name is given to
`chicken-setup', it will simply execute the first file with the
`.setup' extension it can find.

   Use it like any other CHICKEN extension:


$ csi -q
#;1> (require-extension hello)
; loading /usr/local/lib/chicken/1/hello.so ...
#;2> (hello "me")
Hello, me!
#;3>
 Here we create a simple application:

     _;;;; hello2.scm
     _
     (print *"Hello, "*)
     (for-each (*lambda* (x) (printf *"~A "* x)) (command-line-arguments))
     (print *"!"*)
   We also need a setup script:

     _;;;; hello2.setup
     _
     (compile hello2.scm)  _; compile `hello2'
     _(install-program 'hello2 *"hello2"*) _; name of the extension and files to be installed
     _
   To use it, just run `chicken-setup' in the same directory:


$ chicken-setup
 (Here we omit the extension name)

   Now the program `hello2' will be installed in the same location as
the other CHICKEN tools (like `chicken', `csi', etc.), which will
normally be `/usr/local/bin'.  Note that you need write-permissions for
those locations and may have to run `chicken-setup' with administrative
rights.

   Uninstallation is just as easy:


$ chicken-setup -uninstall hello2
 `chicken-setup' provides a `make' macro, so build operations can be of
arbitrary complexity. When running `chicken-setup' with an argument
`NAME', for which no associated file `NAME.setup', `NAME.egg' or
`NAME.scm' exists will ask you to download the extension via HTTP from
the default URL http://www.call-with-current-continuation.org/eggs
(http://www.call-with-current-continuation.org/eggs). You can use the
`-host' option to specify an alternative source location. Extensions
that are required to compile and/or use the requested extension are
downloaded and installed automatically.

   If the given extension name contains a path prefix and the `-host'
option is given, then `chicken-setup' can also download and install
eggs from an arbitrary HTTP server. Alternatively you can pass a full
URL (including the `http://' prefix. Note that no dependency checks are
done when downloading eggs directly with the URL syntax.

   Finally a somewhat more complex example: We want to package a syntax
extension with additional support code that is to be loaded at run-time
of any Scheme code that uses that extension. We create a _glass_
lambda, a procedure with free variables that can be manipulated from
outside:

     _;;;; glass.scm
     _
     (define-macro (glass-lambda llist vars . body)
       _;; Low-level macros are fun!
     _  (*let* ([lvar (gensym)]
     	[svar (gensym)]
     	[x (gensym)]
     	[y (gensym)]
     	[yn (gensym)] )
         `(*let* ,(map (*lambda* (v) (list v #f)) vars)
            (*define* (,svar ,x . ,y)
     	 (*let** ([,yn (pair? ,y)]
     		[,y (*and* ,yn (car ,y))] )
     	   (*case* ,x
     	     ,@(map (*lambda* (v)
     		      `([,v] (*if* ,yn
     				 (*set!* ,v ,y)
     				 ,v) ) )
     		    vars)
     	     (*else* (error *"variable not found"* ,x)) ) ) )
            (*define* ,lvar (*lambda* ,llist ,@body))
            (extend-procedure ,lvar ,svar) ) ) )
   Here some support code that needs to be loaded at runtime:

     _;;;; glass-support.scm
     _
     (require-extension lolevel)

     (*define* *glass-lambda-accessor* procedure-data)
     (*define* (*glass-lambda-ref* gl v) ((procedure-data gl) v))
     (*define* (*glass-lambda-set!* gl v x) ((procedure-data gl) v x))
   The setup script looks like this:

     (compile -s glass-support.scm)

     (install-extension
       'glass
       '(*"glass.scm"* *"glass-support.so"*)
       '((syntax) (require-at-runtime glass-support)) )
   The invocation of `install-extension' provides the files that are to
be copied into the extension repository, and a metadata list that
specifies that the extension `glass' is a syntax extension and that, if
it is declared to be used by other code (either with the
`require-extension' or `require-for-syntax' form), then client code
should perform an implicit `(require 'glass-support)' at startup.

   This can be conveniently packaged as an _egg_:


$ tar cfz glass.egg glass.setup glass.scm glass-support.scm
 And now we use it:


$ chicken-setup glass
$ csi -quiet
#;1> (require-extension glass)
; loading /usr/local/lib/chicken/1/glass.scm ...
; loading /usr/local/lib/chicken/1/glass-support.so ...
#;2> (define foo (glass-lambda (x) (y) (+ x y)))
#;3> (glass-lambda-set! foo 'y 99)
#;4> (foo 33)
132


File: chicken.info,  Node: chicken-setup - chicken-setup reference,  Next: chicken-setup - Windows notes,  Prev: chicken-setup - Examples for extensions,  Up: chicken-setup

40.6 chicken-setup reference
============================

Available options:

`-h  -help'
     Show usage information and exit.

`-V  -version'
     Display version and exit.

`-R  -repository [PATHNAME]'
     When used without an argument, the path of the extension
     repository is displayed on standard output. When given an
     argument, the repository pathname (and the `repository-path'
     parameter) will be set to `PATHNAME' for all subsequent
     operations. The default repository path is the installation
     library directory (usually `/usr/local/lib/chicken'), or (if set)
     the directory given in the environment variable
     `CHICKEN_REPOSITORY'. `PATHNAME' should be an absolute pathname.

`-P  -program-path [PATHNAME]'
     When used without an argument, the path for executables is
     displayed on standard output. When given an argument, the program
     path for installing executables and scripts will be set to
     `PATHNAME' for all subsequent operations. `PATHNAME' should be an
     absolute pathname.

`-h  -host HOSTNAME[:PORT]'
     Specifies alternative host for downloading extensions, optionally
     with a TCP port number (which defaults to 80).

`-u  -uninstall EXTENSION'
     Removes all files that were installed for `EXTENSION' from the
     file-system, together with any metadata that has been stored.

`-l  -list [NAME ...]'
     List all installed extensions or show extension information.

`-r  -run FILENAME'
     Load and execute given file.

`-s  -script FILENAME'
     Executes the given Scheme source file with all remaining arguments
     and exit. The _she-bang_ shell script header is recognized, so you
     can write Scheme scripts that use `chicken-setup' just as with
     `csi'.

`-e  -eval EXPRESSION'
     Evaluates the given expression(s)

`-v  -verbose'
     Display additional debug information

`-k  -keep'
     Keep temporary files and directories

`-c  -csc-option OPTION'
     Passes `OPTION' as an extra argument to invocations of the
     compiler-driver (`csc'); this works only if `csc' is invoked as
     `(run (csc ...))'

`-d  -dont-ask'
     Do not ask the user before trying to download required extensions

`-n  -no-install'
     Do not install generated binaries and/or support files; any
     invocations of `install-program', `install-extension' or
     `install-script' will be be no-ops

`-i  -docindex'
     Displays the path to the index-page of any installed
     extension-documentation; if the index page does not exist, it is
     created

`-t  -test EXTENSION ...'
     return success if all given extensions are installed

`-ls EXTENSION'
     List installed files for extension

`-fetch-tree'
     Download and print the repository catalog

`-create-tree DIRECTORY'
     Create a fresh, minimal repository catalog and writes it to stdout

`-t  -test'
     If the extension sources contain a directory named `tests' and
     this directory includes a file named `run.scm' then this file is
     executed (with `tests' being the current working directory)

`-tree FILENAME'
     Download and show the repository catalog

`-svn URL'
     Fetch extension from Subversion (http://subversion.tigris.org)
     repository

`-svn-trunk URL'
     Fetch extension from trunk in Subversion
     (http://subversion.tigris.org) repository

`-revision REV'
     Specifies SVN revision to check out

`-local PATHNAME'
     Fetch extension from local file

`-install-prefix PATHNAME'
     Specify alternative installation prefix (for packaging)

`-host-extension'
     Compile extension in "host" mode (sets the parameter
     `host-extension' to `#f')

`-build-prefix PATHNAME'
     Location where chicken-setup will create egg build directories
     (default: the value of environment variable CHICKEN_TMPDIR, or
     `/tmp/chicken-{MAJOR-VERSION-build-{USER'}})

`-download-path PATHNAME'
     Location where chicken-setup will save downloaded files  (default:
     `build-prefix/downloads')

`--'
     Ignore all following arguments

   Note that the options are processed exactly in the order in which
they appear in the command-line.


File: chicken.info,  Node: chicken-setup - Windows notes,  Next: chicken-setup - Security,  Prev: chicken-setup - chicken-setup reference,  Up: chicken-setup

40.7 Windows notes
==================

`chicken-setup' works on Windows, when compiled with Visual C++, but
depends on the `tar' and `gunzip' tools to extract the contents of an
egg. The best way is to download an egg either manually (or with
`chicken-setup -fetch') and extract its contents with a separate
program (like `winzip'). the `CHICKEN_REPOSITORY' environment variable
has to be set to a directory where your compiled extensions should be
located.

   The `.setup' scripts will not always work under Windows, and the
extensions may require libraries that are not provided for Windows or
work differently. Under these circumstances it is recommended to
perform the required steps to build an extension manually.

   The required UNIX tools are also available as Windows binaries.
Google or ask on the CHICKEN mailing list if you need help locating
them.


File: chicken.info,  Node: chicken-setup - Security,  Next: chicken-setup - Other modes of installation,  Prev: chicken-setup - Windows notes,  Up: chicken-setup

40.8 Security
=============

When extensions are downloaded and installed one is executing code from
potentially compromised systems. This applies also when `chicken-setup'
executes system tests for required extensions. As the code has been
retrieved over the network effectively untrusted code is going to be
evaluated. When `chicken-setup' is run as _root_ the whole system is at
the mercy of the build instructions (note that this is also the case
every time you install software via `sudo make install', so this is not
specific to the CHICKEN extension mechanism).

   Security-conscious users should never run `chicken-setup' as root. A
simple remedy is to set the environment variable `CHICKEN_REPOSITORY',
which will transparently place the repository at an arbitrary
user-selected location. Alternatively obtain write/execute access to
the default location of the repository (usually
`/usr/local/lib/chicken') to avoid running as root.


File: chicken.info,  Node: chicken-setup - Other modes of installation,  Next: chicken-setup - Linking extensions statically,  Prev: chicken-setup - Security,  Up: chicken-setup

40.9 Other modes of installation
================================

It is possible to install extensions directly from a Subversion
(http://subversion.tigris.org) repository or from a local checkout by
using the `-svn' or `-local' options. By using either the `svn' client
program (which must be installed) or file-system operations, all
necessary files will be copied into the current directory (creating a
subdirectory named `EXTENSIONNAME.egg-dir'), built and subsequently
installed.

   Dependency information, which is necessary to ensure required
extensions are also installed, is downloaded automatically.  If you
have no internet connection or don't want to connect, you can also use
a local file containing the necessary dependency information.  The
`-fetch-tree' option retrieves the canonical _repository file_ at
http://www.call-with-current-continuation.org/eggs/repository
(http://www.call-with-current-continuation.org/eggs/repository),
writing it to stdout. Redirecting this output into a file and passing
the file via the `-tree' option to `chicken-setup' allows you now to
use the local repository file:

   Retrieve complete extension repository (big):


% cd /opt
% svn co uref{https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3, https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3} eggs
 Get your own copy of the repository file:


% chicken-setup -fetch-tree >~/my-repository-file
 Now you can install eggs from your local checkout, with full
dependency tracking and without being connected to the internet:


% cd ~/tmp
% chicken-setup -local /opt/eggs -tree ~/my-repository-file opengl


File: chicken.info,  Node: chicken-setup - Linking extensions statically,  Prev: chicken-setup - Other modes of installation,  Up: chicken-setup

40.10 Linking extensions statically
===================================

The compiler and *Note chicken-setup: chicken-setup. support statically
linked  eggs. The general approach is to generate an object file or
static library (in addition to the usual shared library) in your
`.setup' script and install it along with the dynamically loadable
extension. The setup properties `static'  should contain the name of
the object file (or static library) to be linked, when `csc' gets
passed the `-static-extensions' option:

     (compile -s -O2 -d1 my-ext.scm)   _; dynamically loadable "normal" version
     _(compile -c -O2 -d1 my-ext -unit my-ext)  _; statically linkable version
     _(install-extension
       'my-ext
       '(*"my-ext.so"* *"my-ext.o"*)
       '((static *"my-ext.o"*)) )
   Note the use of the `-unit' option in the second compilation step:
static linking must use static library units. `chicken-setup' will
perform  platform-dependent file-extension translation for the file
list, but does currently not do that for the `static' extension
property.

   To actually link with the static version of `my-ext', do:


% csc -static-extensions my-program.scm -uses my-ext
 The compiler will try to do the right thing, but can not handle all
extensions, since the ability to statically link eggs is relatively
new. Eggs that support static linking are designated as being able to
do so. If you require a statically linkable version of an egg that has
not been converted yet, contact the extension author or the CHICKEN
mailing list.

   Previous: *Note Interface to external functions and variables:
Interface to external functions and variables.

   Next: *Note Data representation: Data representation.


File: chicken.info,  Node: Data representation,  Next: Bugs and limitations,  Prev: chicken-setup,  Up: Top

41 Data representation
**********************

* Menu:

* Data representation - Immediate objects::
* Data representation - Non-immediate objects::

   _Note: In all cases below, bits are numbered starting at 1 and
beginning with the lowest-order bit._

   There exist two different kinds of data objects in the CHICKEN
system: immediate and non-immediate objects.


File: chicken.info,  Node: Data representation - Immediate objects,  Next: Data representation - Non-immediate objects,  Up: Data representation

41.1 Immediate objects
======================

Immediate objects are represented by a single machine word, which is
usually of 32 bits length, or 64 bits on 64-bit architectures.   The
immediate objects come in four different flavors:

   fixnums, that is, small exact integers, where bit 1 is set to 1.
This gives fixnums a range of 31 bits for the actual numeric value (63
bits on 64-bit architectures).

   characters, where bits 1-4 are equal to `C_CHARACTER_BITS'. The
Unicode code point of the character is encoded in bits 9 to 32.

   booleans, where bits 1-4 are equal to `C_BOOLEAN_BITS'. Bit 5 is one
for #t and zero for #f.

   other values: the empty list, the value of unbound identifiers, the
undefined value (void), and end-of-file.  Bits 1-4 are equal to
`C_SPECIAL_BITS'; bits 5 to 8 contain an identifying number for this
type of object.  The following constants are defined:
`C_SCHEME_END_OF_LIST C_SCHEME_UNDEFINED C_SCHEME_UNBOUND
C_SCHEME_END_OF_FILE'

   Collectively, bits 1 and 2 are known as the _immediate mark bits_.
When bit 1 is set, the object is a fixnum, as described above, and bit
2 is part of its value.  When bit 1 is clear but bit 2 is set, it is an
immediate object other than a fixnum.  If neither bit 1 nor bit 2 is
set, the object is non-immediate, as described below.


File: chicken.info,  Node: Data representation - Non-immediate objects,  Prev: Data representation - Immediate objects,  Up: Data representation

41.2 Non-immediate objects
==========================

Non-immediate objects are blocks of data represented by a pointer into
the heap.  The pointer's immediate mark bits (bits 1 and 2) must be
zero to indicate the object is non-immediate; this guarantees the data
block is aligned on a 4-byte boundary, at minimum.  Alignment of data
words is required on modern architectures anyway, so we get the ability
to distinguish between immediate and non-immediate objects for free.

   The first word of the data block contains a header, which gives
information about the type of the object. The header has the size of a
machine word, usually 32 bits (64 bits on 64 bit architectures).

   Bits 1 to 24 contain the length of the data object, which is either
the number of bytes in a string (or byte-vector) or the the number of
elements for a vector or for a structure type.

   Bits 25 to 28 contain the type code of the object.

   Bits 29 to 32 contain miscellaneous flags used for garbage
collection or internal data type dispatching. These flags are:

C_GC_FORWARDING_BIT
     Flag used for forwarding garbage collected object pointers.

C_BYTEBLOCK_BIT
     Flag that specifies whether this data object contains raw bytes (a
     string or byte-vector) or pointers to other data objects.

C_SPECIALBLOCK_BIT
     Flag that specifies whether this object contains a _special_
     non-object pointer value in its first slot. An example for this
     kind of objects are closures, which are a vector-type object with
     the code-pointer as the first item.

C_8ALIGN_BIT
     Flag that specifies whether the data area of this block should be
     aligned on an 8-byte boundary (floating-point numbers, for
     example).

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

   pairs: vector-like object (type bits `C_PAIR_TYPE'), where the car
and the cdr are contained in the first and second slots, respectively.

   vectors: vector object (type bits `C_VECTOR_TYPE').

   strings: byte-vector object (type bits `C_STRING_TYPE').

   procedures: special vector object (type bits `C_CLOSURE_TYPE'). The
first slot contains a pointer to a compiled C function. Any extra slots
contain the free variables (since a flat closure representation is
used).

   flonums: a byte-vector object (type bits `C_FLONUM_BITS'). Slots one
and two (or a single slot on 64 bit architectures) contain a 64-bit
floating-point number, in the representation used by the host systems C
compiler.

   symbols: a vector object (type bits `C_SYMBOL_TYPE'). Slots one and
two contain the toplevel variable value and the print-name (a string)
of the symbol, respectively.

   ports: a special vector object (type bits `C_PORT_TYPE'). The first
slot contains a pointer to a file- stream, if this is a file-pointer,
or NULL if not. The other slots contain housekeeping data used for this
port.

   structures: a vector object (type bits `C_STRUCTURE_TYPE'). The
first slot contains a symbol that specifies the kind of structure this
record is an instance of. The other slots contain the actual record
items.

   pointers: a special vector object (type bits `C_POINTER_TYPE'). The
single slot contains a machine pointer.

   tagged pointers: similar to a pointer (type bits
`C_TAGGED_POINTER_TYPE'), but the object contains an additional slot
with a tag (an arbitrary data object) that identifies the type of the
pointer.

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

   For more information see the header file `chicken.h'.

   Previous: *Note chicken-setup: chicken-setup.

   Next: *Note Bugs and limitations: Bugs and limitations.


File: chicken.info,  Node: Bugs and limitations,  Next: FAQ,  Prev: Data representation,  Up: Top

42 Bugs and limitations
***********************

   * Compiling large files takes too much time.

   * If a known procedure has unused arguments, but is always called
     without those parameters, then the optimizer _repairs_ the
     procedure in certain situations and removes the parameter from the
     lambda-list.

   * `port-position' currently works only for input ports.

   * Leaf routine optimization can theoretically result in code that
     thrashes, if tight loops perform excessively many mutations.

Previous: *Note Data representation: Data representation.

   Next: *Note FAQ: FAQ.


File: chicken.info,  Node: FAQ,  Next: Acknowledgements,  Prev: Bugs and limitations,  Up: Top

43 FAQ
******

* Menu:

* FAQ - General::
* FAQ - Platform specific::
* FAQ - Customization::
* FAQ - Compiled macros::
* FAQ - Warnings and errors::
* FAQ - Optimizations::
* FAQ - Garbage collection::
* FAQ - Interpreter::
* FAQ - Extensions::

   This is the list of Frequently Asked Questions about Chicken Scheme.
If you have a question not answered here, feel free to post to the
chicken-users mailing list; if you consider your question general
enough, feel free to add it to this list.


File: chicken.info,  Node: FAQ - General,  Next: FAQ - Platform specific,  Up: FAQ

43.1 General
============

* Menu:

* FAQ - General - Why yet another Scheme implementation?::
* FAQ - General - Why call it 'Chicken'?::
* FAQ - General - What should I do if I find a bug?::
* FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?::
* FAQ - General - How does cond-expand know which features are registered in used units?::
* FAQ - General - Why are constants defined by define-constant not honoured in case constructs?::
* FAQ - General - How can I enable case sensitive reading/writing in user code?::
* FAQ - General - How can I change match-error-control during compilation?::
* FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?::
* FAQ - General - How can I specialize a generic function method to match instances of every class?::
* FAQ - General - Does CHICKEN support native threads?::
* FAQ - General - Does CHICKEN support Unicode strings?::
* FAQ - General - Why do I get an "Error; invalid syntax; ;;;" using 'match' and 'syntax-case'?::


File: chicken.info,  Node: FAQ - General - Why yet another Scheme implementation?,  Next: FAQ - General - Why call it 'Chicken'?,  Up: FAQ - General

43.1.1 Why yet another Scheme implementation?
---------------------------------------------

Since Scheme is a relatively simple language, a large number of
implementations exist and each has its specific advantages and
disadvantages. Some are fast, some provide a rich programming
environment. Some are free, others are tailored to specific domains,
and so on. The reasons for the existence of CHICKEN are:

   * CHICKEN is portable because it generates C code that runs on a
     large number of platforms.

   * CHICKEN is extendable, since its code generation scheme and
     runtime system/garbage collector fits neatly into a C environment.

   * CHICKEN is free and can be freely distributed, including its
     source code.

   * CHICKEN offers better performance than nearly all interpreter
     based implementations, but still provides full Scheme semantics.

   * As far as we know, CHICKEN is the first implementation of Scheme
     that uses Henry Baker's Cheney on the M.T.A
     (http://home.pipeline.com/~hbaker1/CheneyMTA.html) concept.



File: chicken.info,  Node: FAQ - General - Why call it 'Chicken'?,  Next: FAQ - General - What should I do if I find a bug?,  Prev: FAQ - General - Why yet another Scheme implementation?,  Up: FAQ - General

43.1.2 Why call it 'Chicken'?
-----------------------------

According to felix (http://chicken.wiki.br/felix winkelmann):

     Well, it's pretty boring, really: when I started the project and
     needed some name, the first thing that met my eyes was the
     "chicken" (actually a disguised penguin)  from the Wallace +
     Gromit movie... And then there is of course the ever occurring
     chicken-and-egg problem with bootstrapped compilers.



File: chicken.info,  Node: FAQ - General - What should I do if I find a bug?,  Next: FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?,  Prev: FAQ - General - Why call it 'Chicken'?,  Up: FAQ - General

43.1.3 What should I do if I find a bug?
----------------------------------------

Send e-mail to felix@call-with-current-continuation.org
(mailto:felix@call-with-current-continuation.org) with some hints about
the problem, like version/build of the compiler, platform, system
configuration, code that causes the bug, etc.


File: chicken.info,  Node: FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?,  Next: FAQ - General - How does cond-expand know which features are registered in used units?,  Prev: FAQ - General - What should I do if I find a bug?,  Up: FAQ - General

43.1.4 Why are values defined with `define-foreign-variable' or `define-constant' or `define-inline' not seen outside of the containing source file?
----------------------------------------------------------------------------------------------------------------------------------------------------

Accesses to foreign variables are translated directly into C constructs
that access the variable, so the Scheme name given to that variable
does only exist during compile-time. The same goes for constant- and
inline-definitions: The name is only there to tell the compiler that
this reference is to be replaced with the actual value.


File: chicken.info,  Node: FAQ - General - How does cond-expand know which features are registered in used units?,  Next: FAQ - General - Why are constants defined by define-constant not honoured in case constructs?,  Prev: FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?,  Up: FAQ - General

43.1.5 How does `cond-expand' know which features are registered in used units?
-------------------------------------------------------------------------------

Each unit used via `(declare (uses ...))' is registered as a feature
and so a symbol with the unit-name can be tested by `cond-expand'
during macro-expansion-time. Features registered using the
`register-feature!' procedure are only available during run-time of the
compiled file. You can use the `eval-when' form to register features at
compile time.


File: chicken.info,  Node: FAQ - General - Why are constants defined by define-constant not honoured in case constructs?,  Next: FAQ - General - How can I enable case sensitive reading/writing in user code?,  Prev: FAQ - General - How does cond-expand know which features are registered in used units?,  Up: FAQ - General

43.1.6 Why are constants defined by `define-constant' not honoured in `case' constructs?
----------------------------------------------------------------------------------------

`case' expands into a cascaded `if' expression, where the first item in
each arm is treated as a quoted list. So the `case' macro can not infer
whether a symbol is to be treated as a constant-name (defined via
`define-constant') or a literal symbol.


File: chicken.info,  Node: FAQ - General - How can I enable case sensitive reading/writing in user code?,  Next: FAQ - General - How can I change match-error-control during compilation?,  Prev: FAQ - General - Why are constants defined by define-constant not honoured in case constructs?,  Up: FAQ - General

43.1.7 How can I enable case sensitive reading/writing in user code?
--------------------------------------------------------------------

To enable the `read' procedure to read symbols and identifiers case
sensitive, you can set the parameter `case-sensitivity' to `#t'.


File: chicken.info,  Node: FAQ - General - How can I change match-error-control during compilation?,  Next: FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?,  Prev: FAQ - General - How can I enable case sensitive reading/writing in user code?,  Up: FAQ - General

43.1.8 How can I change `match-error-control' during compilation?
-----------------------------------------------------------------

Use `eval-when', like this:

     (eval-when (compile)
     (match-error-control #:unspecified) )


File: chicken.info,  Node: FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?,  Next: FAQ - General - How can I specialize a generic function method to match instances of every class?,  Prev: FAQ - General - How can I change match-error-control during compilation?,  Up: FAQ - General

43.1.9 Why doesn't CHICKEN support the full numeric tower by default?
---------------------------------------------------------------------

The short answer:

     % chicken-setup numbers
     % csi -q
     #_;1> (use numbers)
     _
   The long answer:

   There are a number of reasons for this:

   - For most applications of Scheme fixnums (exact word-sized
integers) and flonums (64-bit floating-point numbers) are more than
sufficient;

   - Interfacing to C is simpler;

   - Dispatching of arithmetic operations is more efficient.

   There is an extension based on the GNU Multiprecision Package that
implements most of the full numeric tower, see numbers
(http://chicken.wiki.br/numbers).


File: chicken.info,  Node: FAQ - General - How can I specialize a generic function method to match instances of every class?,  Next: FAQ - General - Does CHICKEN support native threads?,  Prev: FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?,  Up: FAQ - General

43.1.10 How can I specialize a generic function method to match instances of every class?
-----------------------------------------------------------------------------------------

Specializing a method on `<object>' doesn't work on primitive data
objects like numbers, strings, etc. so for example

     (define-method (foo (x <my-class>)) ...)
     (define-method (foo (x <object>)) ...)
     (foo 123)
   will signal an error, because to applicable method can be found. To
specialize a method for primitive objects, use `<top>':

     (define-method (foo (x <top>)) ...)


File: chicken.info,  Node: FAQ - General - Does CHICKEN support native threads?,  Next: FAQ - General - Does CHICKEN support Unicode strings?,  Prev: FAQ - General - How can I specialize a generic function method to match instances of every class?,  Up: FAQ - General

43.1.11 Does CHICKEN support native threads?
--------------------------------------------

Native threads are not supported for two reasons. One, the runtime
system is not reentrant.  Two, concurrency implemented properly would
require mandatory locking of every object that could be potentially
shared between two threads. The garbage-collection algorithm would then
become much more complex and inefficient, since the location of every
object has to be accessed via a thread synchronization protocol. Such a
design would make native threads in Chicken essentially equivalent to
Unix processes and shared memory.

   For a different approach to concurrency, please see the mpi
(http://www.call-with-current-continuation.org/eggs/3/mpi.html) egg.


File: chicken.info,  Node: FAQ - General - Does CHICKEN support Unicode strings?,  Next: FAQ - General - Why do I get an "Error; invalid syntax; ;;;" using 'match' and 'syntax-case'?,  Prev: FAQ - General - Does CHICKEN support native threads?,  Up: FAQ - General

43.1.12 Does CHICKEN support Unicode strings?
---------------------------------------------

Yes, as an extension.

   By default all string and character functions operate bytewise, so
that characters with an iteger value greater than 255 don't make much
sense and multibyte UTF-8 characters are seen and manipulated as
separate bytes, analogous to what a C program would see.

   You can enable UTF-8 support by placing the following two lines at
the beginning of your source file (or in your ~/.csirc for interactive
sessions) before any other code, including other use directives:

     (use iset syntax-case utf8)
     (import utf8)
   This will replace all builtin string operators with UTF-8-aware
versions, that will treat strings as sequences of multibyte UTF-8
characters, thus enabling you to represent and manipulate Unicode
characters while remaining compatible with most C libraries and system
interfaces.

   Most eggs should work correctly in utf8 mode, including the regex
extension, but you still have the option of working around
incompatibilities of specific eggs by loading them before the (import
utf8) directive. Keep in mind that some operations, such as
string-length, are much more expensive in utf8 (multibyte) mode, and
should be used with care. See the utf8 egg documentation
(http://www.call-with-current-continuation.org/eggs/utf8.html) for
details.


File: chicken.info,  Node: FAQ - General - Why do I get an "Error; invalid syntax; ;;;" using 'match' and 'syntax-case'?,  Prev: FAQ - General - Does CHICKEN support Unicode strings?,  Up: FAQ - General

43.1.13 Why do I get an "Error: invalid syntax: ..." using 'match' and 'syntax-case'?
-------------------------------------------------------------------------------------

The built-in 'match' macro is incompatible with 'syntax-case'. Use the
matchable egg
(http://www.call-with-current-continuation.org/eggs/matchable.html)
instead.


File: chicken.info,  Node: FAQ - Platform specific,  Next: FAQ - Customization,  Prev: FAQ - General,  Up: FAQ

43.2 Platform specific
======================

* Menu:

* FAQ - Platform specific - How do I generate a DLL under MS Windows ;tm; ?::
* FAQ - Platform specific - How do I generate a GUI application under Windows;tm;?::
* FAQ - Platform specific - Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space;::
* FAQ - Platform specific - When I run csi inside an emacs buffer under Windows; nothing happens;::
* FAQ - Platform specific - I load compiled code dynamically in a Windows GUI application and it crashes;::
* FAQ - Platform specific - On Windows; csc;exe seems to be doing something wrong;::
* FAQ - Platform specific - On Windows source and/or output filenames with embedded whitespace are not found;::


File: chicken.info,  Node: FAQ - Platform specific - How do I generate a DLL under MS Windows ;tm; ?,  Next: FAQ - Platform specific - How do I generate a GUI application under Windows;tm;?,  Up: FAQ - Platform specific

43.2.1 How do I generate a DLL under MS Windows (tm) ?
------------------------------------------------------

Use `csc' in combination with the `-dll' option:

   `C:\> csc foo.scm -dll'


File: chicken.info,  Node: FAQ - Platform specific - How do I generate a GUI application under Windows;tm;?,  Next: FAQ - Platform specific - Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space;,  Prev: FAQ - Platform specific - How do I generate a DLL under MS Windows ;tm; ?,  Up: FAQ - Platform specific

43.2.2 How do I generate a GUI application under Windows(tm)?
-------------------------------------------------------------

Invoke `csc' with the `-windows' option. Or pass the `-DC_WINDOWS_GUI'
option to the C compiler and link with the GUI version of the runtime
system (that's `libchicken-gui[-static].lib'. The GUI runtime displays
error messages in a message box and does some rudimentary command-line
parsing.


File: chicken.info,  Node: FAQ - Platform specific - Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space;,  Next: FAQ - Platform specific - When I run csi inside an emacs buffer under Windows; nothing happens;,  Prev: FAQ - Platform specific - How do I generate a GUI application under Windows;tm;?,  Up: FAQ - Platform specific

43.2.3 Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space.
--------------------------------------------------------------------------------------------------------------------------------------

It seems that the Microsoft C compiler can only handle files up to a
certain size, and it doesn't utilize virtual memory as well as the GNU
C compiler, for example. Try closing running applications. If that
fails, try to break up the Scheme code into several library units.


File: chicken.info,  Node: FAQ - Platform specific - When I run csi inside an emacs buffer under Windows; nothing happens;,  Next: FAQ - Platform specific - I load compiled code dynamically in a Windows GUI application and it crashes;,  Prev: FAQ - Platform specific - Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space;,  Up: FAQ - Platform specific

43.2.4 When I run `csi' inside an emacs buffer under Windows, nothing happens.
------------------------------------------------------------------------------

Invoke `csi' with the `-:c' runtime option. Under Windows the
interpreter thinks it is not running under control of a terminal and
doesn't print the prompt and does not flush the output stream properly.


File: chicken.info,  Node: FAQ - Platform specific - I load compiled code dynamically in a Windows GUI application and it crashes;,  Next: FAQ - Platform specific - On Windows; csc;exe seems to be doing something wrong;,  Prev: FAQ - Platform specific - When I run csi inside an emacs buffer under Windows; nothing happens;,  Up: FAQ - Platform specific

43.2.5 I load compiled code dynamically in a Windows GUI application and it crashes.
------------------------------------------------------------------------------------

Code compiled into a DLL to be loaded dynamically must be linked with
the same runtime system as the loading application. That means that all
dynamically loaded entities (including extensions built and installed
with `chicken-setup') must be compiled with the `-windows' `csc' option.


File: chicken.info,  Node: FAQ - Platform specific - On Windows; csc;exe seems to be doing something wrong;,  Next: FAQ - Platform specific - On Windows source and/or output filenames with embedded whitespace are not found;,  Prev: FAQ - Platform specific - I load compiled code dynamically in a Windows GUI application and it crashes;,  Up: FAQ - Platform specific

43.2.6 On Windows, `csc.exe' seems to be doing something wrong.
---------------------------------------------------------------

The Windows development tools include a C# compiler with the same name.
Either invoke `csc.exe' with a full pathname, or put the directory
where you installed CHICKEN in front of the MS development tool path in
the `PATH' environment variable.


File: chicken.info,  Node: FAQ - Platform specific - On Windows source and/or output filenames with embedded whitespace are not found;,  Prev: FAQ - Platform specific - On Windows; csc;exe seems to be doing something wrong;,  Up: FAQ - Platform specific

43.2.7 On Windows source and/or output filenames with embedded whitespace are not found.
----------------------------------------------------------------------------------------

There is no current workaround. Do not use filenames with embedded
whitespace for code. However, command names with embedded whitespace
will work correctly.


File: chicken.info,  Node: FAQ - Customization,  Next: FAQ - Compiled macros,  Prev: FAQ - Platform specific,  Up: FAQ

43.3 Customization
==================

* Menu:

* FAQ - Customization - How do I run custom startup code before the runtime-system is invoked?::
* FAQ - Customization - How can I add compiled user passes?::


File: chicken.info,  Node: FAQ - Customization - How do I run custom startup code before the runtime-system is invoked?,  Next: FAQ - Customization - How can I add compiled user passes?,  Up: FAQ - Customization

43.3.1 How do I run custom startup code before the runtime-system is invoked?
-----------------------------------------------------------------------------

When you invoke the C compiler for your translated Scheme source
program, add the C compiler option `-DC_EMBEDDED', or pass `-embedded'
to the `csc' driver program, so no entry-point function will be
generated (`main()'). When your are finished with your startup
processing, invoke:

     *CHICKEN_main*(argc, argv, C_toplevel);
   where `C_toplevel' is the entry-point into the compiled Scheme code.
You should add the following  declarations at the head of your code:

     #*include* *"chicken.h"*
     *extern* *void* *C_toplevel*(C_word,C_word,C_word) C_noret;


File: chicken.info,  Node: FAQ - Customization - How can I add compiled user passes?,  Prev: FAQ - Customization - How do I run custom startup code before the runtime-system is invoked?,  Up: FAQ - Customization

43.3.2 How can I add compiled user passes?
------------------------------------------

To add a compiled user pass instead of an interpreted one, create a
library unit and recompile the main unit of the compiler (in the file
`chicken.scm') with an additional `uses' declaration. Then link all
compiler modules and your (compiled) extension to create a new version
of the compiler, like this (assuming all sources are in the current
directory):

     % cat userpass.scm
     _;;;; userpass.scm - My very own compiler pass
     _
     (declare (unit userpass))

     _;; Perhaps more user passes/extensions are added:
     _(*let* ([old (user-pass)])
     (user-pass
     (*lambda* (x)
     (*let* ([x2 (do-something-with x)])
     	  (*if* old
     	      (old x2)
     	      x2) ) ) ) )


% csc -c -x userpass.scm
% csc chicken.scm -c -o chicken-extended.o -uses userpass
% gcc chicken-extended.o support.o easyffi.o compiler.o optimizer.o batch-driver.o c-platform.o \
c-backend.o userpass.o `csc -ldflags -libs` -o chicken-extended
 On platforms that support it (Linux ELF, Solaris, Windows + VC++),
compiled code can be loaded via `-extend' just like source files (see
`load' in the User's Manual).


File: chicken.info,  Node: FAQ - Compiled macros,  Next: FAQ - Warnings and errors,  Prev: FAQ - Customization,  Up: FAQ

43.4 Compiled macros
====================

* Menu:

* FAQ - Compiled macros - Why is define-macro complaining about unbound variables?::
* FAQ - Compiled macros - Why isn't load properly loading my library of macros?::
* FAQ - Compiled macros - Why is include unable to load my hygienic macros?::
* FAQ - Compiled macros - Why are macros not visible outside of the compilation unit in which they are defined?::


File: chicken.info,  Node: FAQ - Compiled macros - Why is define-macro complaining about unbound variables?,  Next: FAQ - Compiled macros - Why isn't load properly loading my library of macros?,  Up: FAQ - Compiled macros

43.4.1 Why is `define-macro' complaining about unbound variables?
-----------------------------------------------------------------

Macro bodies that are defined and used in a compiled source-file are
evaluated during compilation and so have no access to anything created
with `define'. Use `define-for-syntax' instead.


File: chicken.info,  Node: FAQ - Compiled macros - Why isn't load properly loading my library of macros?,  Next: FAQ - Compiled macros - Why is include unable to load my hygienic macros?,  Prev: FAQ - Compiled macros - Why is define-macro complaining about unbound variables?,  Up: FAQ - Compiled macros

43.4.2 Why isn't `load' properly loading my library of macros?
--------------------------------------------------------------

During compile-time, macros are only available in the source file in
which they are defined. Files included via `include' are considered
part of the containing file.


File: chicken.info,  Node: FAQ - Compiled macros - Why is include unable to load my hygienic macros?,  Next: FAQ - Compiled macros - Why are macros not visible outside of the compilation unit in which they are defined?,  Prev: FAQ - Compiled macros - Why isn't load properly loading my library of macros?,  Up: FAQ - Compiled macros

43.4.3 Why is `include' unable to load my hygienic macros?
----------------------------------------------------------

It is not sufficient for the included file to require the `syntax-case'
extension. Call `(require-extension syntax-case)' _before_ calling
`include'.


File: chicken.info,  Node: FAQ - Compiled macros - Why are macros not visible outside of the compilation unit in which they are defined?,  Prev: FAQ - Compiled macros - Why is include unable to load my hygienic macros?,  Up: FAQ - Compiled macros

43.4.4 Why are macros not visible outside of the compilation unit in which they are defined?
--------------------------------------------------------------------------------------------

Macros are defined during compile time, so when a file has been
compiled, the definitions are gone. An exception to this rule are
macros defined with `define-macro', which are also visible at run-time,
i.e. in `eval'. To use macros defined in other files, use the `include'
special form.


File: chicken.info,  Node: FAQ - Warnings and errors,  Next: FAQ - Optimizations,  Prev: FAQ - Compiled macros,  Up: FAQ

43.5 Warnings and errors
========================

* Menu:

* FAQ - Warnings and errors - Why does my program crash when I use callback functions ;from Scheme to C and back to Scheme again;?::
* FAQ - Warnings and errors - Why does the linker complain about a missing function _C_;;;_toplevel?::
* FAQ - Warnings and errors - Why does the linker complain about a missing function _C_toplevel?::
* FAQ - Warnings and errors - Why does my program crash when I compile a file with -unsafe or unsafe declarations?::
* FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?::
* FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?::
* FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?::
* FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?::
* FAQ - Warnings and errors - How can I increase the size of the trace shown when runtime errors are detected?::


File: chicken.info,  Node: FAQ - Warnings and errors - Why does my program crash when I use callback functions ;from Scheme to C and back to Scheme again;?,  Next: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_;;;_toplevel?,  Up: FAQ - Warnings and errors

43.5.1 Why does my program crash when I use callback functions (from Scheme to C and back to Scheme again)?
-----------------------------------------------------------------------------------------------------------

There are two reasons why code involving callbacks can crash out of no
apparent reason:

  1. It is important to use `foreign-safe-lambda/foreign-safe-lambda*'
     for the C code that is to call back into Scheme. If this is not
     done than sooner or later the available stack space will be
     exhausted.

  2. If the C code uses a large amount of stack storage, or if
     Scheme-to-C-to-Scheme calls are nested deeply, then the available
     nursery space on the stack will run low. To avoid this it might be
     advisable to run the compiled code with a larger nursery setting,
     i.e. run the code with `-:s...' and a larger value than the
     default (for example `-:s300k'), or use the `-nursery' compiler
     option.  Note that this can decrease runtime performance on some
     platforms.



File: chicken.info,  Node: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_;;;_toplevel?,  Next: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_toplevel?,  Prev: FAQ - Warnings and errors - Why does my program crash when I use callback functions ;from Scheme to C and back to Scheme again;?,  Up: FAQ - Warnings and errors

43.5.2 Why does the linker complain about a missing function `_C_..._toplevel'?
-------------------------------------------------------------------------------

This message indicates that your program uses a library-unit, but that
the object-file or library was not supplied to the linker. If you have
the unit `foo', which is contained in `foo.o' than you have to supply
it to the linker like this (assuming a GCC environment):

   `% csc program.scm foo.o -o program'


File: chicken.info,  Node: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_toplevel?,  Next: FAQ - Warnings and errors - Why does my program crash when I compile a file with -unsafe or unsafe declarations?,  Prev: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_;;;_toplevel?,  Up: FAQ - Warnings and errors

43.5.3 Why does the linker complain about a missing function `_C_toplevel'?
---------------------------------------------------------------------------

This means you have compiled a library unit as an application. When a
unit-declaration (as in `(declare (unit ...))') is given, then this
file has a specially named toplevel entry procedure. Just remove the
declaration, or compile this file to an object-module and link it to
your application code.


File: chicken.info,  Node: FAQ - Warnings and errors - Why does my program crash when I compile a file with -unsafe or unsafe declarations?,  Next: FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?,  Prev: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_toplevel?,  Up: FAQ - Warnings and errors

43.5.4 Why does my program crash when I compile a file with `-unsafe' or unsafe declarations?
---------------------------------------------------------------------------------------------

The compiler option `-unsafe' or the declaration `(declare (unsafe))'
disable certain safety-checks to improve performance, so code that
would normally trigger an error will work unexpectedly or even crash
the running application. It is advisable to develop and debug a program
in safe mode (without unsafe declarations) and use this feature only if
the application works properly.


File: chicken.info,  Node: FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?,  Next: FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?,  Prev: FAQ - Warnings and errors - Why does my program crash when I compile a file with -unsafe or unsafe declarations?,  Up: FAQ - Warnings and errors

43.5.5 Why do I get a warning when I define a global variable named `match'?
----------------------------------------------------------------------------

Even when the `match' unit is not used, the macros from that package
are visible in the compiler. The reason for this is that macros can not
be accessed from library units (only when explicitly evaluated in
running code). To speed up macro-expansion time, the compiler and the
interpreter both already provide the compiled  `match-...' macro
definitions. Macros shadowed lexically are no problem, but global
definitions of variables named identically to (global) macros are
useless - the macro definition shadows the global variable.

   This problem can be solved using a different name or undefining the
macro, like this:

     (eval-when (compile eval) (undefine-macro! 'match))


File: chicken.info,  Node: FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?,  Next: FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?,  Prev: FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?,  Up: FAQ - Warnings and errors

43.5.6 Why don't toplevel-continuations captured in interpreted code work?
--------------------------------------------------------------------------

Consider the following piece of code:


     (*define* *k* (call-with-current-continuation (*lambda* (k) k)))
     (k k)
   When compiled, this will loop endlessly. But when interpreted, `(k
k)' will return to the read-eval-print loop! This happens because the
continuation captured will eventually read the next toplevel expression
from the standard-input (or an input-file if loading from a file). At
the moment `k' was defined, the next expression was `(k k)'. But when
`k' is invoked, the next expression will be whatever follows after `(k
k)'. In other words, invoking a captured continuation will not rewind
the file-position of the input source. A solution is to wrap the whole
code into a `(begin ...)' expression, so all toplevel expressions will
be loaded together.


File: chicken.info,  Node: FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?,  Next: FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?,  Prev: FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?,  Up: FAQ - Warnings and errors

43.5.7 Why does `define-reader-ctor' not work in my compiled program?
---------------------------------------------------------------------

The following piece of code does not work as expected:

     (eval-when (compile)
     (define-reader-ctor 'integer->char integer->char) )
     (print #,(integer->char 33))
   The problem is that the compiler reads the complete source-file
before doing any processing on it, so the sharp-comma form is
encountered before the reader-ctor is defined. A possible solution is
to include the file containing the sharp-comma form, like this:

     (eval-when (compile)
     (define-reader-ctor 'integer->char integer->char) )

     (include *"other-file"*)

     _;;; other-file.scm:
     _(print #,(integer->char 33))


File: chicken.info,  Node: FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?,  Next: FAQ - Warnings and errors - How can I increase the size of the trace shown when runtime errors are detected?,  Prev: FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?,  Up: FAQ - Warnings and errors

43.5.8 Why do built-in units, such as srfi-1, srfi-18, and posix fail to load?
------------------------------------------------------------------------------

When you try to `use' a built-in unit such as `srfi-18', you may get
the following error:

     #_;1> (use srfi-18)
     __; loading library srfi-18 ...
     _Error: (load-library) unable to load library
     srfi-18
     *"dlopen(libchicken.dylib, 9): image not found"*                _;; on a Mac
     _*"libchicken.so: cannot open shared object file: No such file or directory"*  _;; Linux
     _
   Another symptom is that `(require 'srfi-18)' will silently fail.

   This typically happens because the Chicken libraries have been
installed in a non-standard location, such as your home directory.  The
workaround is to explicitly tell the dynamic linker where to look for
your libraries:


export DYLD_LIBRARY_PATH=~/scheme/chicken/lib:$DYLD_LIBRARY_PATH ;; Mac
export LD_LIBRARY_PATH=~/scheme/chicken/lib:$LD_LIBRARY_PATH    ;; Linux


File: chicken.info,  Node: FAQ - Warnings and errors - How can I increase the size of the trace shown when runtime errors are detected?,  Prev: FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?,  Up: FAQ - Warnings and errors

43.5.9 How can I increase the size of the trace shown when runtime errors are detected?
---------------------------------------------------------------------------------------

When a runtime error is detected, Chicken will print the last entries
from the trace of functions called (unless your executable was compiled
with the `-no-trace' option. By default, only 16 entries will be shown.
To increase this number pass the `-:aN' parameter to your executable.


File: chicken.info,  Node: FAQ - Optimizations,  Next: FAQ - Garbage collection,  Prev: FAQ - Warnings and errors,  Up: FAQ

43.6 Optimizations
==================

* Menu:

* FAQ - Optimizations - How can I obtain smaller executables?::
* FAQ - Optimizations - How can I obtain faster executables?::
* FAQ - Optimizations - Which non-standard procedures are treated specially when the extended-bindings or usual-integrations declaration or compiler option is used?::
* FAQ - Optimizations - Can I load compiled code at runtime?::


File: chicken.info,  Node: FAQ - Optimizations - How can I obtain smaller executables?,  Next: FAQ - Optimizations - How can I obtain faster executables?,  Up: FAQ - Optimizations

43.6.1 How can I obtain smaller executables?
--------------------------------------------

If you don't need `eval' or the stuff in the `extras' library unit,
you can just use the `library' unit:

     	(declare (uses library))
     	(display *"Hello, world!\n"*)
   (Don't forget to compile with the `-explicit-use' option) Compiled
with Visual C++ this generates an executable of around 240 kilobytes.
It is theoretically possible to compile something without the library,
but a program would have to implement quite a lot of support code on
its own.


File: chicken.info,  Node: FAQ - Optimizations - How can I obtain faster executables?,  Next: FAQ - Optimizations - Which non-standard procedures are treated specially when the extended-bindings or usual-integrations declaration or compiler option is used?,  Prev: FAQ - Optimizations - How can I obtain smaller executables?,  Up: FAQ - Optimizations

43.6.2 How can I obtain faster executables?
-------------------------------------------

There are a number of declaration specifiers that should be used to
speed up compiled files: declaring `(standard-bindings)' is mandatory,
since this enables most optimizations. Even if some standard procedures
should be redefined, you can list untouched bindings in the
declaration. Declaring `(extended-bindings)' lets the compiler choose
faster versions of certain internal library functions. This might give
another speedup. You can also use the the `usual-integrations'
declaration, which is identical to declaring `standard-bindings' and
`extended-bindings' (note that `usual-integrations' is set by default).
Declaring `(block)' tells the compiler that global procedures are not
changed outside the current compilation unit, this gives the compiler
some more  opportunities for optimization. If no floating point
arithmetic is required, then declaring `(number-type fixnum)' can give
a big performance improvement, because the compiler can now inline most
arithmetic operations.  Declaring `(unsafe)' will switch off most
safety checks. If threads are not used, you can declare
`(disable-interrupts)'. You should always use maximum optimizations
settings for your C compiler. Good GCC compiler options on Pentium (and
compatible) hardware are: `-Os -fomit-frame-pointer
-fno-strict-aliasing' Some programs are very sensitive to the setting
of the nursery (the first heap-generation). You should experiment with
different nursery settings (either by compiling with the `-nursery'
option or by using the `-:s...' runtime option).


File: chicken.info,  Node: FAQ - Optimizations - Which non-standard procedures are treated specially when the extended-bindings or usual-integrations declaration or compiler option is used?,  Next: FAQ - Optimizations - Can I load compiled code at runtime?,  Prev: FAQ - Optimizations - How can I obtain faster executables?,  Up: FAQ - Optimizations

43.6.3 Which non-standard procedures are treated specially when the `extended-bindings' or `usual-integrations' declaration or compiler option is used?
-------------------------------------------------------------------------------------------------------------------------------------------------------

The following standard bindings are handled specially, depending on
optimization options and compiler settings:


code{+} code{*} code{-} code{/} code{quotient} code{eq?} code{eqv?} code{equal?} code{apply} code{c...r} code{values} code{call-with-values}
code{list-ref} code{null?} code{length} code{not} code{char?} code{string?} code{symbol?} code{vector?} code{pair?} code{procedure?}
code{boolean?} code{number?} code{complex?} code{rational?} code{real?} code{exact?} code{inexact?} code{list?} code{eof-object?}
code{string-ref} code{string-set!} code{vector-ref} code{vector-set!} code{char=?} code{char<?} code{char>?} code{char<=?} code{char>=?}
code{char-numeric?} code{char-alphabetic?} code{char-whitespace?} code{char-upper-case?}
code{char-lower-case?} code{char-upcae} code{char-downcase} code{list-tail} code{assv} code{memv} code{memq} code{assoc}
code{member} code{set-car!} code{set-cdr!} code{abs} code{exp} code{sin} code{cos} code{tan} code{log} code{asin} code{acos} code{atan} code{sqrt}
code{zero?} code{positive?} code{negative?} code{vector-length} code{string-length} code{char->integer}
code{integer->char} code{inexact->exact} code{=} code{>} code{<} code{>=} code{<=} code{for-each} code{map} code{substring}
code{string-append} code{gcd} code{lcm} code{list} code{exact->inexact} code{string->number} code{number->string}
code{even?} code{odd?} code{remainder} code{floor} code{ceiling} code{truncate} code{round} code{cons} code{vector} code{string}
code{string=?} code{string-ci=?} code{make-vector} code{call-with-current-continuation}
code{write-char} code{read-string}
 The following extended bindings are handled specially:

   `bitwise-and' `bitwise-ior' `bitwise-xor' `bitwise-not'  `bit-set?'
`add1' `sub1' `fx+' `fx-' `fx*' `fx/' `fxmod' `fx=' `fx>' `fx>='
`fixnum?' `fxneg' `fxmax' `fxmin' `fxand' `fxior' `fxxor' `fxnot'
`fxshl' `fxshr' `flonum?' `fp+' `fp-' `fp*' `fp/' `atom?' `fp=' `fp>'
`fp>=' `fpneg' `fpmax' `fpmin' `arithmetic-shift' `signum'
`flush-output' `thread-specific' `thread-specific-set!' `not-pair?'
`null-list?' `print' `print*' `u8vector->blob/shared'
`s8vector->blob/shared' `u16vector->blob/shared'
`s16vector->blob/shared' `u32vector->blob/shared'
`s32vector->blob/shared' `f32vector->blob/shared'
`f64vector->blob/shared' `block-ref' `blob-size' `u8vector-length'
`s8vector-length' `u16vector-length' `s16vector-length'
`u32vector-length' `s32vector-length' `f32vector-length'
`f64vector-length' `u8vector-ref' `s8vector-ref' `u16vector-ref'
`s16vector-ref' `u32vector-ref' `s32vector-ref' `f32vector-ref'
`f64vector-ref' `u8vector-set!' `s8vector-set!' `u16vector-set!'
`s16vector-set!' `u32vector-set!' `s32vector-set!' `hash-table-ref'
`block-set!' `number-of-slots' `first' `second' `third' `fourth'
`null-pointer?' `pointer->object' `make-record-instance' `locative-ref'
`locative-set!' `locative?' `locative->object' `identity' `cpu-time'
`error' `call/cc' `any?' `substring=?' `substring-ci=?'
`substring-index' `substring-index-ci'


File: chicken.info,  Node: FAQ - Optimizations - Can I load compiled code at runtime?,  Prev: FAQ - Optimizations - Which non-standard procedures are treated specially when the extended-bindings or usual-integrations declaration or compiler option is used?,  Up: FAQ - Optimizations

43.6.4 Can I load compiled code at runtime?
-------------------------------------------

Yes. You can load compiled at code at runtime with `load' just as well
as you can load Scheme source code. Compiled code will, of course, run
faster.

   To do this, pass to `load' a path for a shared object. Use a form
such as `(load "foo.so")' and run `csc -shared foo.scm' to produce
`foo.so' from `foo.scm' (at which point `foo.scm' will no longer be
required).


File: chicken.info,  Node: FAQ - Garbage collection,  Next: FAQ - Interpreter,  Prev: FAQ - Optimizations,  Up: FAQ

43.7 Garbage collection
=======================

* Menu:

* FAQ - Garbage collection - Why does a loop that doesn't cons still trigger garbage collections?::
* FAQ - Garbage collection - Why do finalizers not seem to work in simple cases in the interpeter?::


File: chicken.info,  Node: FAQ - Garbage collection - Why does a loop that doesn't cons still trigger garbage collections?,  Next: FAQ - Garbage collection - Why do finalizers not seem to work in simple cases in the interpeter?,  Up: FAQ - Garbage collection

43.7.1 Why does a loop that doesn't `cons' still trigger garbage collections?
-----------------------------------------------------------------------------

Under CHICKENs implementation policy, tail recursion is achieved simply
by avoiding to return from a function call. Since the programs are CPS
converted, a continuous  sequence of nested procedure calls is
performed. At some stage the stack-space has to run out and the current
procedure and its parameters (including the current continuation) are
stored somewhere in the runtime system. Now a minor garbage collection
occurs and rescues all live data from the stack (the first heap
generation) and moves it into the the second heap generation. Then the
stack is cleared (using a `longjmp') and execution can continue from
the saved state. With this method arbitrary recursion (in tail- or
non-tail position) can happen,  provided the application doesn't run
out of heap-space. (The difference between a tail- and a non-tail call
is that the tail-call has no live data after it invokes its
continuation - and so the amount of heap-space needed stays constant)


File: chicken.info,  Node: FAQ - Garbage collection - Why do finalizers not seem to work in simple cases in the interpeter?,  Prev: FAQ - Garbage collection - Why does a loop that doesn't cons still trigger garbage collections?,  Up: FAQ - Garbage collection

43.7.2 Why do finalizers not seem to work in simple cases in the interpeter?
----------------------------------------------------------------------------

Consider the following interaction in CSI:


#;1> (define x '(1 2 3))
#;2> (define (yammer x) (print x " is dead"))
#;3> (set-finalizer! x yammer)
(1 2 3)
#;4> (gc #t)
157812
#;5> (define x #f)
#;6> (gc #t)
157812
#;7>
 While you might expect objects to be reclaimed and "_(1 2 3) is dead_"
printed, it won't happen: the literal list gets held in the interpreter
history, because it is the result value of the set-finalizer! call.
Running this in a normal program will work fine.

   When testing finalizers from the interpreter, you might want to
define a trivial macro such as


(define-macro (v x) `(begin (print ,x) (void)))
 and wrap calls to `set-finalizer!' in it.


File: chicken.info,  Node: FAQ - Interpreter,  Next: FAQ - Extensions,  Prev: FAQ - Garbage collection,  Up: FAQ

43.8 Interpreter
================

* Menu:

* FAQ - Interpreter - Does CSI support history and autocompletion?::
* FAQ - Interpreter - Does code loaded with load run compiled or interpreted?::


File: chicken.info,  Node: FAQ - Interpreter - Does CSI support history and autocompletion?,  Next: FAQ - Interpreter - Does code loaded with load run compiled or interpreted?,  Up: FAQ - Interpreter

43.8.1 Does CSI support history and autocompletion?
---------------------------------------------------

CSI doesn't support it natively but it can be activated with the
http://www.call-with-current-continuation.org/eggs/readline.html
(http://www.call-with-current-continuation.org/eggs/readline.html) egg.
After installing the egg, add the following to your `~/.csirc' or
equivalent file:

     (require-extension readline)
     (current-input-port (make-gnu-readline-port))
     (gnu-history-install-file-manager (string-append (*or* (getenv *"HOME"*) *"."*) *"/.csi.history"*))
   Users of *nix-like systems (including Cygwin), may also want to
check out rlwrap (http://utopia.knoware.nl/~hlub/rlwrap/).  This
program lets you "wrap" another process (e.g. `rlwrap csi') with the
readline library, giving you history, autocompletion, and the ability
to set the keystroke set. Vi fans can get vi keystrokes by adding "set
editing-mode vi" to their `.inputrc' file.


File: chicken.info,  Node: FAQ - Interpreter - Does code loaded with load run compiled or interpreted?,  Prev: FAQ - Interpreter - Does CSI support history and autocompletion?,  Up: FAQ - Interpreter

43.8.2 Does code loaded with `load' run compiled or interpreted?
----------------------------------------------------------------

If you compile a file with a call to `load', the code will be loaded at
runtime and, if the file loaded is a Scheme source code file (instead
of a shared object), it will be interpreted (even if the caller program
is compiled).


File: chicken.info,  Node: FAQ - Extensions,  Prev: FAQ - Interpreter,  Up: FAQ

43.9 Extensions
===============

* Menu:

* FAQ - Extensions - How can I install Chicken eggs to a non-default location?::
* FAQ - Extensions - Can I install chicken eggs as a non-root user?::


File: chicken.info,  Node: FAQ - Extensions - How can I install Chicken eggs to a non-default location?,  Next: FAQ - Extensions - Can I install chicken eggs as a non-root user?,  Up: FAQ - Extensions

43.9.1 How can I install Chicken eggs to a non-default location?
----------------------------------------------------------------

You can just set the `CHICKEN_REPOSITORY' environment variable. It
should contain the path where you want eggs to be installed:


$ export CHICKEN_REPOSITORY=~/chicken/
$ chicken-setup extensionname
 In order to make programs (including csi) see these eggs, you should
set this variable when you run them. Alternatively, you can call the
`repository-path' Scheme procedure before loading the eggs, as in:

     (repository-path *"/home/azul/chicken"*)
     (use format-modular)
   Note, however, that using `repository-path' as above hard-codes the
location of your eggs in your source files.  While this might not be an
issue in your case, it might be safe to keep this configuration outside
of the source code (that is, specifying it as an environment variable)
to make it easier to maintain.


File: chicken.info,  Node: FAQ - Extensions - Can I install chicken eggs as a non-root user?,  Prev: FAQ - Extensions - How can I install Chicken eggs to a non-default location?,  Up: FAQ - Extensions

43.9.2 Can I install chicken eggs as a non-root user?
-----------------------------------------------------

Yes, just *Note install them in a directory you can write: FAQ -
Extensions - How can I install Chicken eggs to a non-default location?.

   Previous: *Note Bugs and limitations: Bugs and limitations.

   Next: *Note Acknowledgements: Acknowledgements.


File: chicken.info,  Node: Acknowledgements,  Next: Bibliography,  Prev: FAQ,  Up: Top

44 Acknowledgements
*******************

Many thanks to Nico Amtsberg, Alonso Andres, William Annis, Marc Baily,
Peter Barabas, Jonah Beckford, Arto Bendiken, Peter Bex, Jean-Francois
Bignolles, Alaric Blagrave-Snellpym, Dave Bodenstab, Fabian Boehlke, T.
Kurt Bond, Ashley Bone, Dominique Boucher, Terence Brannon, Roy Bryant,
Adam Buchbinder, Hans Bulfone, Category 5, Taylor Campbell, Naruto
Canada, Esteban U. Caamano Castro, Franklin Chen, Thomas Chust, Gian
Paolo Ciceri, John Cowan, Grzegorz Chrupa&#322;a, James Crippen, Tollef
Fog Heen, Alejandro Forero Cuervo, Linh Dang, Brian Denheyer, dgym,
Don, Chris Double, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B.
Faken, Will Farr, Graham Fawcett, Marc Feeley, Fizzie, Kimura Fuyuki,
Tony Garnock-Jones, Martin Gasbichler, Joey Gibson, Stephen C. Gilardi,
Joshua Griffith, Johannes Groedem, Damian Gryski, Mario Domenech
Goulart, Andreas Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino,
Ahdi Hargo, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann,
Bill Hoffman, Bruce Hoult, Hans Huebner, Markus Huelsmann, Goetz
Isenmann, Paulo Jabardo, David Janssens, Christian Jaeger, Dale Jordan,
Valentin Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel,
Matthias Koeppe, Krysztof Kowa&#322;czyk, Andre Kuehne, Todd R. Kueny
Sr, Goran Krampe, David Krentzlin, Ben Kurtz, Micky Latowicki, John
Lenz, Kirill Lisovsky, Juergen Lorenz, Kon Lovett, Dennis Marti,
Charles Martin, Bob McIsaac, Alain Mellan, Eric Merrit, Perry Metzger,
Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline, Eric E. Moore,
Julian Morrison, Dan Muresan, Lars Nilsson, Ian Oversby, o.t., Gene
Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita, Robin Lee
Powell, Pupeno, Davide Puricelli, Doug Quale, Eric Raible, Ivan Raikov,
Joel Reymont, Eric Rochester, Andreas Rottman, David Rush, Lars
Rustemeier, Daniel Sadilek, Oskar Schirmer, Burton Samograd, Reed
Sheridan, Ronald Schroeder, Spencer Schumann, Alex Shinn, Ivan Shmakov,
Shmul, Tony Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele
Simionato, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels,
Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Rick
Taube, Nathan Thern, Mike Thomas, Minh Thu, Christian Tismer, Andre van
Tonder, John Tobey, Henrik Tramberend, Vladimir Tsichevsky, Neil van
Dyke, Sander Vesik, Jaques Vidrine, Panagiotis Vossos, Shawn Wagner,
Peter Wang, Ed Watkeys, Brad Watson, Thomas Weidner, Goeran Weinholt,
Matthew Welland, Joerg Wittenberger, Peter Wright, Mark Wutka, Richard
Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.

   CHICKEN uses the PCRE regular expression package
(http://www.pcre.org (http://www.pcre.org)), which is written by Philip
Hazel.

   Special thanks to Brandon van Every for contributing the (now
defunct) CMake (http://www.cmake.org) support and for helping with
Windows build issues.

   Also special thanks to Benedikt Rosenau for his constant
encouragement.

   Thanks to Dunja Winkelmann for putting up with all of this.

   CHICKEN contains code from several people:

Eli Barzilay
     some performance tweaks used in TinyCLOS.

Mikael Djurfeldt
     topological sort used by compiler.

Marc Feeley
     pretty-printer.

Aubrey Jaffer
     implementation of `dynamic-wind'.

Richard O'Keefe
     sorting routines.

Olin Shivers
     implementation of `let-optionals[*]' and reference implementations
     of SRFI-1, SRFI-13 and SRFI-14.

Andrew Wilcox
     queues.

Andrew Wright
     pattern matcher.

Alex Shinn (http://chicken.wiki.br/Alex Shinn)
     `scheme-complete.el' emacs tab-completion

   Previous: *Note FAQ: FAQ.

   Next: *Note Bibliography: Bibliography.


File: chicken.info,  Node: Bibliography,  Prev: Acknowledgements,  Up: Top

45 Bibliography
***************

Henry Baker: _CONS Should Not CONS Its Arguments, Part II: Cheney on
the M.T.A._ http://home.pipeline.com/~hbaker1/CheneyMTA.html
(http://home.pipeline.com/~hbaker1/CheneyMTA.html)

   _Revised^5 Report on the Algorithmic Language Scheme_
http://www.schemers.org/Documents/Standards/R5RS
(http://www.schemers.org/Documents/Standards/R5RS)

   Previous: *Note Acknowledgements: Acknowledgements.



Tag Table:
Node: Top308
Node: The User's Manual1423
Node: Getting started2892
Node: Getting started - Scheme4165
Node: Getting started - Chicken6258
Node: Getting started - Chicken repositories; websites; and community12011
Node: Getting started - Installing Chicken13732
Node: Getting started - Development environments16990
Node: Getting started - The Read-Eval-Print loop21287
Node: Getting started - The Read-Eval-Print loop - Scripts23145
Node: Getting started - The compiler24656
Node: Getting started - Installing an egg28437
Node: Getting started - Accessing C libraries30255
Node: Basic mode of operation32099
Node: Using the compiler34513
Node: Using the compiler - Compiler command line format35270
Node: Using the compiler - Runtime options49442
Node: Using the compiler - Examples52471
Node: Using the compiler - Examples - A simple example ;with one source file;52833
Node: Using the compiler - Examples - A simple example ;with one source file; - Writing your source file53580
Node: Using the compiler - Examples - A simple example ;with one source file; - Compiling your program54189
Node: Using the compiler - Examples - A simple example ;with one source file; - Running your program54773
Node: Using the compiler - Examples - An example with multiple files55388
Node: Using the compiler - Examples - An example with multiple files - Writing your source files56152
Node: Using the compiler - Examples - An example with multiple files - Compiling and running your program57335
Node: Using the compiler - Extending the compiler58516
Node: Using the compiler - Distributing compiled C files62508
Node: Using the interpreter64940
Node: Using the interpreter - Interpreter command line format65621
Node: Using the interpreter - Writing Scheme scripts69525
Node: Using the interpreter - Toplevel commands71553
Node: Using the interpreter - toplevel-command74221
Node: Using the interpreter - History access74817
Node: Using the interpreter - set-describer!75512
Node: Using the interpreter - Auto-completion and edition76343
Node: Using the interpreter - Accessing documentation77374
Node: Supported language78428
Node: Deviations from the standard80274
Node: Extensions to the standard83019
Node: Non-standard read syntax92036
Node: Non-standard read syntax - Multiline Block Comment92991
Node: Non-standard read syntax - Expression Comment93338
Node: Non-standard read syntax - External Representation93917
Node: Non-standard read syntax - Syntax Expression94390
Node: Non-standard read syntax - Location Expression94714
Node: Non-standard read syntax - Keyword95028
Node: Non-standard read syntax - Multiline String Constant95385
Node: Non-standard read syntax - Multiline String Constant with Embedded Expressions95949
Node: Non-standard read syntax - Foreign Declare96820
Node: Non-standard read syntax - Sharp Prefixed Symbol97167
Node: Non-standard read syntax - Bang97460
Node: Non-standard read syntax - Bang - Line Comment98083
Node: Non-standard read syntax - Bang - Eof Object98400
Node: Non-standard read syntax - Bang - DSSSL Formal Parameter List Annotation98801
Node: Non-standard read syntax - Bang - Read Mark Invocation99313
Node: Non-standard read syntax - Case Sensitive Expression99743
Node: Non-standard read syntax - Case Insensitive Expression100125
Node: Non-standard read syntax - Conditional Expansion100530
Node: Non-standard macros and special forms100992
Node: Non-standard macros and special forms - Making extra libraries and extensions available101712
Node: Non-standard macros and special forms - Making extra libraries and extensions available - require-extension102299
Node: Non-standard macros and special forms - Making extra libraries and extensions available - define-extension106231
Node: Non-standard macros and special forms - Binding forms for optional arguments107804
Node: Non-standard macros and special forms - Binding forms for optional arguments - optional108596
Node: Non-standard macros and special forms - Binding forms for optional arguments - case-lambda109369
Node: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals110343
Node: Non-standard macros and special forms - Binding forms for optional arguments - let-optionals*111365
Node: Non-standard macros and special forms - Other binding forms112400
Node: Non-standard macros and special forms - Other binding forms - and-let*113595
Node: Non-standard macros and special forms - Other binding forms - rec114522
Node: Non-standard macros and special forms - Other binding forms - cut115181
Node: Non-standard macros and special forms - Other binding forms - define-values115669
Node: Non-standard macros and special forms - Other binding forms - fluid-let116160
Node: Non-standard macros and special forms - Other binding forms - let-values116675
Node: Non-standard macros and special forms - Other binding forms - let*-values117200
Node: Non-standard macros and special forms - Other binding forms - letrec-values117854
Node: Non-standard macros and special forms - Other binding forms - parameterize118678
Node: Non-standard macros and special forms - Other binding forms - receive119364
Node: Non-standard macros and special forms - Other binding forms - set!-values120029
Node: Non-standard macros and special forms - Substitution forms and macros120428
Node: Non-standard macros and special forms - Substitution forms and macros - define-constant121152
Node: Non-standard macros and special forms - Substitution forms and macros - define-inline122262
Node: Non-standard macros and special forms - Substitution forms and macros - define-macro123515
Node: Non-standard macros and special forms - Substitution forms and macros - define-for-syntax124985
Node: Non-standard macros and special forms - Conditional forms125600
Node: Non-standard macros and special forms - Conditional forms - select126144
Node: Non-standard macros and special forms - Conditional forms - unless126532
Node: Non-standard macros and special forms - Conditional forms - when126973
Node: Non-standard macros and special forms - Record structures127327
Node: Non-standard macros and special forms - Record structures - define-record127889
Node: Non-standard macros and special forms - Record structures - define-record-printer128789
Node: Non-standard macros and special forms - Record structures - define-record-type130124
Node: Non-standard macros and special forms - Other forms130751
Node: Non-standard macros and special forms - Other forms - assert131453
Node: Non-standard macros and special forms - Other forms - cond-expand132103
Node: Non-standard macros and special forms - Other forms - ensure133995
Node: Non-standard macros and special forms - Other forms - eval-when134987
Node: Non-standard macros and special forms - Other forms - include136433
Node: Non-standard macros and special forms - Other forms - nth-value137088
Node: Non-standard macros and special forms - Other forms - time137531
Node: Pattern matching138060
Node: Pattern matching - Pattern Matching Expressions139727
Node: Pattern matching - Patterns144934
Node: Pattern matching - Match Failure149577
Node: Pattern matching - Record Structures Pattern151592
Node: Pattern matching - Code Generation152158
Node: Declarations153182
Node: Declarations - declare154479
Node: Declarations - always-bound155098
Node: Declarations - block155422
Node: Declarations - block-global155719
Node: Declarations - hide155890
Node: Declarations - bound-to-procedure156359
Node: Declarations - c-options156685
Node: Declarations - check-c-syntax157150
Node: Declarations - constant157528
Node: Declarations - export157922
Node: Declarations - emit-exports158307
Node: Declarations - emit-external-prototypes-first158618
Node: Declarations - disable-interrupts159109
Node: Declarations - disable-warning159576
Node: Declarations - import159927
Node: Declarations - inline160391
Node: Declarations - inline-limit161113
Node: Declarations - interrupts-enabled161454
Node: Declarations - keep-shadowed-macros161786
Node: Declarations - lambda-lift162275
Node: Declarations - link-options162575
Node: Declarations - no-argc-checks163075
Node: Declarations - no-bound-checks163350
Node: Declarations - no-procedure-checks163651
Node: Declarations - post-process163990
Node: Declarations - profile164610
Node: Declarations - number-type165048
Node: Declarations - fixnum-arithmetic165233
Node: Declarations - run-time-macros165645
Node: Declarations - standard-bindings166022
Node: Declarations - extended-bindings166561
Node: Declarations - usual-integrations167127
Node: Declarations - unit167784
Node: Declarations - unsafe168042
Node: Declarations - unused168436
Node: Declarations - uses168765
Node: Parameters169443
Node: Parameters - make-parameter170724
Node: Parameters - case-sensitive171418
Node: Parameters - dynamic-load-libraries171764
Node: Parameters - command-line-arguments172161
Node: Parameters - current-read-table172536
Node: Parameters - exit-handler172874
Node: Parameters - eval-handler173243
Node: Parameters - force-finalizers173645
Node: Parameters - implicit-exit-handler174036
Node: Parameters - keyword-style174442
Node: Parameters - load-verbose174810
Node: Parameters - program-name175124
Node: Parameters - repl-prompt175479
Node: Parameters - reset-handler175835
Node: Unit library176333
Node: Unit library - Arithmetic177458
Node: Unit library - Arithmetic - add1/sub1178007
Node: Unit library - Arithmetic - Binary integer operations178275
Node: Unit library - Arithmetic - bit-set?179025
Node: Unit library - Arithmetic - fixnum?179437
Node: Unit library - Arithmetic - Arithmetic fixnum operations179755
Node: Unit library - Arithmetic - Arithmetic floating-point operations180859
Node: Unit library - Arithmetic - signum181728
Node: Unit library - Arithmetic - finite?182110
Node: Unit library - File Input/Output182383
Node: Unit library - File Input/Output - current-output-port182910
Node: Unit library - File Input/Output - current-error-port183462
Node: Unit library - File Input/Output - flush-output184085
Node: Unit library - File Input/Output - port-name184500
Node: Unit library - File Input/Output - port-position185015
Node: Unit library - File Input/Output - set-port-name!185588
Node: Unit library - Files185890
Node: Unit library - Files - delete-file186188
Node: Unit library - Files - file-exists?186494
Node: Unit library - Files - rename-file186829
Node: Unit library - String ports187162
Node: Unit library - String ports - get-output-string187515
Node: Unit library - String ports - open-input-string187848
Node: Unit library - String ports - open-output-string188208
Node: Unit library - Feature identifiers188518
Node: Unit library - Feature identifiers - features189582
Node: Unit library - Feature identifiers - feature?189923
Node: Unit library - Feature identifiers - register-feature!190312
Node: Unit library - Feature identifiers - unregister-feature!190804
Node: Unit library - Keywords191196
Node: Unit library - Keywords - get-keyword191989
Node: Unit library - Keywords - keyword?192742
Node: Unit library - Keywords - keyword->string193054
Node: Unit library - Keywords - string->keyword193373
Node: Unit library - Exceptions193654
Node: Unit library - Exceptions - condition-case194181
Node: Unit library - Exceptions - breakpoint195455
Node: Unit library - Environment information and system interface198024
Node: Unit library - Environment information and system interface - argv199316
Node: Unit library - Environment information and system interface - exit199943
Node: Unit library - Environment information and system interface - build-platform200511
Node: Unit library - Environment information and system interface - chicken-version201083
Node: Unit library - Environment information and system interface - errno201674
Node: Unit library - Environment information and system interface - getenv202099
Node: Unit library - Environment information and system interface - machine-byte-order202585
Node: Unit library - Environment information and system interface - machine-type203102
Node: Unit library - Environment information and system interface - on-exit203697
Node: Unit library - Environment information and system interface - software-type204352
Node: Unit library - Environment information and system interface - software-version204923
Node: Unit library - Environment information and system interface - c-runtime205544
Node: Unit library - Environment information and system interface - system206218
Node: Unit library - Execution time206771
Node: Unit library - Execution time - cpu-time207236
Node: Unit library - Execution time - current-milliseconds207707
Node: Unit library - Execution time - current-seconds208096
Node: Unit library - Execution time - current-gc-milliseconds208475
Node: Unit library - Interrupts and error-handling208906
Node: Unit library - Interrupts and error-handling - enable-warnings209743
Node: Unit library - Interrupts and error-handling - error210351
Node: Unit library - Interrupts and error-handling - get-call-chain211030
Node: Unit library - Interrupts and error-handling - print-call-chain211818
Node: Unit library - Interrupts and error-handling - print-error-message212320
Node: Unit library - Interrupts and error-handling - procedure-information213028
Node: Unit library - Interrupts and error-handling - reset213548
Node: Unit library - Interrupts and error-handling - warning213915
Node: Unit library - Interrupts and error-handling - singlestep214352
Node: Unit library - Garbage collection214700
Node: Unit library - Garbage collection - gc215156
Node: Unit library - Garbage collection - memory-statistics215655
Node: Unit library - Garbage collection - set-finalizer!216307
Node: Unit library - Garbage collection - set-gc-report!217009
Node: Unit library - Other control structures217484
Node: Unit library - Other control structures - promise?217783
Node: Unit library - String utilities218046
Node: Unit library - String utilities - reverse-list->string218344
Node: Unit library - Generating uninterned symbols218714
Node: Unit library - Generating uninterned symbols - gensym219111
Node: Unit library - Generating uninterned symbols - string->uninterned-symbol219519
Node: Unit library - Standard Input/Output219917
Node: Unit library - Standard Input/Output - port?220324
Node: Unit library - Standard Input/Output - print220605
Node: Unit library - Standard Input/Output - print*221058
Node: Unit library - User-defined named characters221427
Node: Unit library - User-defined named characters - char-name221739
Node: Unit library - Blobs222984
Node: Unit library - Blobs - make-blob223530
Node: Unit library - Blobs - blob?223811
Node: Unit library - Blobs - blob-size224090
Node: Unit library - Blobs - blob->string224369
Node: Unit library - Blobs - string->blob224671
Node: Unit library - Blobs - blob=?224972
Node: Unit library - Vectors225257
Node: Unit library - Vectors - vector-copy!225527
Node: Unit library - Vectors - vector-resize226009
Node: Unit library - The unspecified value226517
Node: Unit library - The unspecified value - void226786
Node: Unit library - Continuations226982
Node: Unit library - Continuations - call/cc227444
Node: Unit library - Continuations - continuation-capture227723
Node: Unit library - Continuations - continuation?228448
Node: Unit library - Continuations - continuation-graft229054
Node: Unit library - Continuations - continuation-return229467
Node: Unit library - Setters229987
Node: Unit library - Setters - setter230377
Node: Unit library - Setters - getter-with-setter230913
Node: Unit library - Reader extensions231338
Node: Unit library - Reader extensions - define-reader-ctor231849
Node: Unit library - Reader extensions - set-read-syntax!232298
Node: Unit library - Reader extensions - set-sharp-read-syntax!233764
Node: Unit library - Reader extensions - set-parameterized-read-syntax!234324
Node: Unit library - Reader extensions - copy-read-table235066
Node: Unit library - Property lists235469
Node: Unit library - Property lists - get236064
Node: Unit library - Property lists - put!236466
Node: Unit library - Property lists - remprop!236891
Node: Unit library - Property lists - symbol-plist237323
Node: Unit library - Property lists - get-properties237712
Node: Unit eval238398
Node: Unit eval - Loading code238879
Node: Unit eval - Loading code - load239261
Node: Unit eval - Loading code - load-relative240361
Node: Unit eval - Loading code - load-noisily240728
Node: Unit eval - Loading code - load-library241651
Node: Unit eval - Loading code - set-dynamic-load-mode!242653
Node: Unit eval - Read-eval-print loop244038
Node: Unit eval - Read-eval-print loop - repl244284
Node: Unit eval - Macros244703
Node: Unit eval - Macros - get-line-number245120
Node: Unit eval - Macros - macro?245654
Node: Unit eval - Macros - macroexpand245945
Node: Unit eval - Macros - macroexpand-1246319
Node: Unit eval - Macros - undefine-macro!246648
Node: Unit eval - Macros - syntax-error246977
Node: Unit eval - Loading extension libraries247296
Node: Unit eval - Loading extension libraries - repository-path248069
Node: Unit eval - Loading extension libraries - extension-information248578
Node: Unit eval - Loading extension libraries - provide249150
Node: Unit eval - Loading extension libraries - provided?249597
Node: Unit eval - Loading extension libraries - require250003
Node: Unit eval - Loading extension libraries - set-extension-specifier!251141
Node: Unit eval - System information252607
Node: Unit eval - System information - chicken-home252866
Node: Unit eval - Eval253287
Node: Unit eval - Eval - eval253448
Node: Unit data-structures253825
Node: Unit data-structures - Lists254417
Node: Unit data-structures - Lists - alist-ref255092
Node: Unit data-structures - Lists - alist-update!255517
Node: Unit data-structures - Lists - atom?256161
Node: Unit data-structures - Lists - rassoc256552
Node: Unit data-structures - Lists - butlast256962
Node: Unit data-structures - Lists - chop257280
Node: Unit data-structures - Lists - compress257828
Node: Unit data-structures - Lists - flatten258301
Node: Unit data-structures - Lists - intersperse258652
Node: Unit data-structures - Lists - join258983
Node: Unit data-structures - Lists - shuffle259644
Node: Unit data-structures - Lists - tail?259992
Node: Unit data-structures - Queues260259
Node: Unit data-structures - Queues - list->queue260995
Node: Unit data-structures - Queues - make-queue261460
Node: Unit data-structures - Queues - queue?261764
Node: Unit data-structures - Queues - queue->list262078
Node: Unit data-structures - Queues - queue-add!262568
Node: Unit data-structures - Queues - queue-empty?262888
Node: Unit data-structures - Queues - queue-first263232
Node: Unit data-structures - Queues - queue-last263599
Node: Unit data-structures - Queues - queue-remove!263963
Node: Unit data-structures - Queues - queue-push-back!264354
Node: Unit data-structures - Queues - queue-push-back-list!264782
Node: Unit data-structures - Sorting265175
Node: Unit data-structures - Sorting - merge265514
Node: Unit data-structures - Sorting - sort265987
Node: Unit data-structures - Sorting - sorted?266382
Node: Unit data-structures - Random numbers266672
Node: Unit data-structures - Random numbers - random-seed266952
Node: Unit data-structures - Strings267265
Node: Unit data-structures - Strings - conc268036
Node: Unit data-structures - Strings - ->string268445
Node: Unit data-structures - Strings - string-chop268754
Node: Unit data-structures - Strings - string-chomp269220
Node: Unit data-structures - Strings - string-compare3269711
Node: Unit data-structures - Strings - string-intersperse270336
Node: Unit data-structures - Strings - string-split270965
Node: Unit data-structures - Strings - string-translate271724
Node: Unit data-structures - Strings - string-translate*272391
Node: Unit data-structures - Strings - substring=?273188
Node: Unit data-structures - Strings - substring-index273869
Node: Unit data-structures - Combinators274421
Node: Unit data-structures - Combinators - any?275524
Node: Unit data-structures - Combinators - none?275818
Node: Unit data-structures - Combinators - always?276168
Node: Unit data-structures - Combinators - never?276527
Node: Unit data-structures - Combinators - constantly276888
Node: Unit data-structures - Combinators - complement277343
Node: Unit data-structures - Combinators - compose277765
Node: Unit data-structures - Combinators - conjoin278378
Node: Unit data-structures - Combinators - disjoin278850
Node: Unit data-structures - Combinators - each279320
Node: Unit data-structures - Combinators - flip279917
Node: Unit data-structures - Combinators - identity280318
Node: Unit data-structures - Combinators - project280632
Node: Unit data-structures - Combinators - list-of280986
Node: Unit data-structures - Combinators - noop281512
Node: Unit data-structures - Combinators - o281851
Node: Unit data-structures - Combinators - left-section282208
Node: Unit data-structures - Combinators - right-section282689
Node: Unit data-structures - Binary searching283136
Node: Unit data-structures - Binary searching - binary-search283391
Node: Unit ports284085
Node: Unit ports - Input/output port extensions284522
Node: Unit ports - Input/output port extensions - with-output-to-port285074
Node: Unit ports - Input/output port extensions - make-input-port285468
Node: Unit ports - Input/output port extensions - make-output-port286497
Node: Unit ports - Input/output port extensions - with-error-output-to-port287252
Node: Unit ports - Input/output port extensions - with-input-from-port287750
Node: Unit ports - String-port extensions288157
Node: Unit ports - String-port extensions - call-with-input-string288653
Node: Unit ports - String-port extensions - call-with-output-string289078
Node: Unit ports - String-port extensions - with-input-from-string289579
Node: Unit ports - String-port extensions - with-output-to-string290088
Node: Unit ports - Port iterators290529
Node: Unit ports - Port iterators - port-for-each290867
Node: Unit ports - Port iterators - port-map291235
Node: Unit ports - Port iterators - port-fold291655
Node: Unit ports - Funky ports292118
Node: Unit ports - Funky ports - make-broadcast-port292376
Node: Unit ports - Funky ports - make-concatenated-port292813
Node: Unit files293380
Node: Unit files - Pathname operations293761
Node: Unit files - Pathname operations - absolute-pathname?294715
Node: Unit files - Pathname operations - decompose-pathname295092
Node: Unit files - Pathname operations - make-pathname295622
Node: Unit files - Pathname operations - make-absolute-pathname295911
Node: Unit files - Pathname operations - pathname-directory296845
Node: Unit files - Pathname operations - pathname-file297188
Node: Unit files - Pathname operations - pathname-extension297512
Node: Unit files - Pathname operations - pathname-replace-directory297984
Node: Unit files - Pathname operations - pathname-replace-file298373
Node: Unit files - Pathname operations - pathname-replace-extension298754
Node: Unit files - Pathname operations - pathname-strip-directory299242
Node: Unit files - Pathname operations - pathname-strip-extension299626
Node: Unit files - Pathname operations - directory-null?300075
Node: Unit files - Temporary files300475
Node: Unit files - Temporary files - create-temporary-file300767
Node: Unit files - Deleting a file without signalling an error301213
Node: Unit files - Deleting a file without signalling an error - delete-file*301575
Node: Unit files - File move/copy301954
Node: Unit files - File move/copy - file-copy302233
Node: Unit files - File move/copy - file-move302998
Node: Unit extras303677
Node: Unit extras - Formatted output304081
Node: Unit extras - Formatted output - printf304430
Node: Unit extras - Formatted output - fprintf304615
Node: Unit extras - Formatted output - sprintf304851
Node: Unit extras - Formatted output - format306411
Node: Unit extras - Random numbers306926
Node: Unit extras - Random numbers - random-seed307273
Node: Unit extras - Random numbers - random307614
Node: Unit extras - Random numbers - randomize307921
Node: Unit extras - Input/Output extensions308331
Node: Unit extras - Input/Output extensions - pretty-print309195
Node: Unit extras - Input/Output extensions - pretty-print-width309591
Node: Unit extras - Input/Output extensions - read-byte309997
Node: Unit extras - Input/Output extensions - write-byte310282
Node: Unit extras - Input/Output extensions - read-file310775
Node: Unit extras - Input/Output extensions - read-line311689
Node: Unit extras - Input/Output extensions - write-line311965
Node: Unit extras - Input/Output extensions - read-lines312688
Node: Unit extras - Input/Output extensions - read-string313267
Node: Unit extras - Input/Output extensions - read-string!313552
Node: Unit extras - Input/Output extensions - write-string313843
Node: Unit extras - Input/Output extensions - read-token314898
Node: Unit srfi-1315475
Node: Unit srfi-4315780
Node: Unit srfi-4 - make-XXXvector317800
Node: Unit srfi-4 - u8vector->blob318690
Node: Unit srfi-4 - s8vector->blob318882
Node: Unit srfi-4 - u16vector->blob319075
Node: Unit srfi-4 - s16vector->blob319271
Node: Unit srfi-4 - u32vector->blob319468
Node: Unit srfi-4 - s32vector->blob319665
Node: Unit srfi-4 - f32vector->blob319862
Node: Unit srfi-4 - f64vector->blob320059
Node: Unit srfi-4 - u8vector->blob/shared320262
Node: Unit srfi-4 - s8vector->blob/shared320485
Node: Unit srfi-4 - u16vector->blob/shared320715
Node: Unit srfi-4 - s16vector->blob/shared320948
Node: Unit srfi-4 - u32vector->blob/shared321182
Node: Unit srfi-4 - s32vector->blob/shared321416
Node: Unit srfi-4 - f32vector->blob/shared321650
Node: Unit srfi-4 - f64vector->blob/shared321884
Node: Unit srfi-4 - blob->u8vector323078
Node: Unit srfi-4 - blob->s8vector323280
Node: Unit srfi-4 - blob->u16vector323475
Node: Unit srfi-4 - blob->s16vector323673
Node: Unit srfi-4 - blob->u32vector323872
Node: Unit srfi-4 - blob->s32vector324071
Node: Unit srfi-4 - blob->f32vector324270
Node: Unit srfi-4 - blob->f64vector324469
Node: Unit srfi-4 - blob->u8vector/shared324674
Node: Unit srfi-4 - blob->s8vector/shared324897
Node: Unit srfi-4 - blob->u16vector/shared325127
Node: Unit srfi-4 - blob->s16vector/shared325360
Node: Unit srfi-4 - blob->u32vector/shared325594
Node: Unit srfi-4 - blob->s32vector/shared325828
Node: Unit srfi-4 - blob->f32vector/shared326062
Node: Unit srfi-4 - blob->f64vector/shared326296
Node: Unit srfi-4 - subu8vector327359
Node: Unit srfi-4 - subu16vector327550
Node: Unit srfi-4 - subu32vector327733
Node: Unit srfi-4 - subs8vector327916
Node: Unit srfi-4 - subs16vector328097
Node: Unit srfi-4 - subs32vector328280
Node: Unit srfi-4 - subf32vector328464
Node: Unit srfi-4 - subf64vector328648
Node: Unit srfi-4 - read-u8vector329378
Node: Unit srfi-4 - read-u8vector!329863
Node: Unit srfi-4 - write-u8vector330430
Node: Unit srfi-13330894
Node: Unit srfi-14331368
Node: Unit srfi-69331910
Node: Unit srfi-69 - Hash Table Procedures332323
Node: Unit srfi-69 - Hash Table Procedures - make-hash-table334439
Node: Unit srfi-69 - Hash Table Procedures - hash-table?335331
Node: Unit srfi-69 - Hash Table Procedures - hash-table-size335688
Node: Unit srfi-69 - Hash Table Procedures - hash-table-equivalence-function336068
Node: Unit srfi-69 - Hash Table Procedures - hash-table-hash-function336527
Node: Unit srfi-69 - Hash Table Procedures - hash-table-min-load336962
Node: Unit srfi-69 - Hash Table Procedures - hash-table-max-load337374
Node: Unit srfi-69 - Hash Table Procedures - hash-table-weak-keys337782
Node: Unit srfi-69 - Hash Table Procedures - hash-table-weak-values338206
Node: Unit srfi-69 - Hash Table Procedures - hash-table-has-initial?338642
Node: Unit srfi-69 - Hash Table Procedures - hash-table-initial339083
Node: Unit srfi-69 - Hash Table Procedures - hash-table-keys339490
Node: Unit srfi-69 - Hash Table Procedures - hash-table-values339901
Node: Unit srfi-69 - Hash Table Procedures - hash-table->alist340319
Node: Unit srfi-69 - Hash Table Procedures - alist->hash-table340747
Node: Unit srfi-69 - Hash Table Procedures - hash-table-ref341291
Node: Unit srfi-69 - Hash Table Procedures - hash-table-ref/default341755
Node: Unit srfi-69 - Hash Table Procedures - hash-table-exists?342243
Node: Unit srfi-69 - Hash Table Procedures - hash-table-set!342655
Node: Unit srfi-69 - Hash Table Procedures - hash-table-update!343233
Node: Unit srfi-69 - Hash Table Procedures - hash-table-update!/default344034
Node: Unit srfi-69 - Hash Table Procedures - hash-table-copy344701
Node: Unit srfi-69 - Hash Table Procedures - hash-table-delete!345108
Node: Unit srfi-69 - Hash Table Procedures - hash-table-remove!345523
Node: Unit srfi-69 - Hash Table Procedures - hash-table-clear!346027
Node: Unit srfi-69 - Hash Table Procedures - hash-table-merge346423
Node: Unit srfi-69 - Hash Table Procedures - hash-table-merge!346873
Node: Unit srfi-69 - Hash Table Procedures - hash-table-map347317
Node: Unit srfi-69 - Hash Table Procedures - hash-table-fold347795
Node: Unit srfi-69 - Hash Table Procedures - hash-table-for-each348337
Node: Unit srfi-69 - Hash Table Procedures - hash-table-walk348788
Node: Unit srfi-69 - Hashing Functions349164
Node: Unit srfi-69 - Hashing Functions - number-hash349977
Node: Unit srfi-69 - Hashing Functions - object-uid-hash350292
Node: Unit srfi-69 - Hashing Functions - symbol-hash350656
Node: Unit srfi-69 - Hashing Functions - keyword-hash351029
Node: Unit srfi-69 - Hashing Functions - string-hash351402
Node: Unit srfi-69 - Hashing Functions - string-ci-hash351779
Node: Unit srfi-69 - Hashing Functions - eq?-hash352164
Node: Unit srfi-69 - Hashing Functions - eqv?-hash352521
Node: Unit srfi-69 - Hashing Functions - equal?-hash352879
Node: Unit srfi-69 - Hashing Functions - hash353241
Node: Unit srfi-69 - Hashing Functions - hash-by-identity353556
Node: Unit match353930
Node: Unit regex354440
Node: Unit regex - grep355513
Node: Unit regex - glob->regexp355877
Node: Unit regex - glob?356284
Node: Unit regex - regexp356636
Node: Unit regex - regexp*357170
Node: Unit regex - regexp?359199
Node: Unit regex - regexp-optimize359463
Node: Unit regex - string-match359821
Node: Unit regex - string-match-positions360012
Node: Unit regex - string-search361255
Node: Unit regex - string-search-positions361459
Node: Unit regex - string-split-fields361940
Node: Unit regex - string-substitute362845
Node: Unit regex - string-substitute*363777
Node: Unit regex - regexp-escape364479
Node: Unit regex - make-anchored-pattern364910
Node: Unit srfi-18365598
Node: Unit srfi-18 - thread-signal!367748
Node: Unit srfi-18 - thread-quantum368116
Node: Unit srfi-18 - thread-quantum-set!368484
Node: Unit srfi-18 - thread-suspend!368791
Node: Unit srfi-18 - thread-resume!369085
Node: Unit srfi-18 - thread-wait-for-i/o!369366
Node: Unit srfi-18 - time->milliseconds369854
Node: Unit srfi-18 - milliseconds->time370253
Node: Unit posix371000
Node: Unit posix - Constants372424
Node: Unit posix - Constants - File-control Commands372763
Node: Unit posix - Constants - File-control Commands - fcntl/dupfd373326
Node: Unit posix - Constants - File-control Commands - fcntl/getfd373582
Node: Unit posix - Constants - File-control Commands - fcntl/setfd373907
Node: Unit posix - Constants - File-control Commands - fcntl/getfl374232
Node: Unit posix - Constants - File-control Commands - fcntl/setfl374557
Node: Unit posix - Constants - Standard I/O file-descriptors374813
Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin375335
Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout375620
Node: Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr375986
Node: Unit posix - Constants - Open flags376274
Node: Unit posix - Constants - Open flags - open/rdonly377326
Node: Unit posix - Constants - Open flags - open/wronly377549
Node: Unit posix - Constants - Open flags - open/rdwr377828
Node: Unit posix - Constants - Open flags - open/read378101
Node: Unit posix - Constants - Open flags - open/write378373
Node: Unit posix - Constants - Open flags - open/creat378648
Node: Unit posix - Constants - Open flags - open/append378925
Node: Unit posix - Constants - Open flags - open/excl379203
Node: Unit posix - Constants - Open flags - open/noctty379478
Node: Unit posix - Constants - Open flags - open/nonblock379759
Node: Unit posix - Constants - Open flags - open/trunc380047
Node: Unit posix - Constants - Open flags - open/sync380327
Node: Unit posix - Constants - Open flags - open/fsync380602
Node: Unit posix - Constants - Open flags - open/binary380880
Node: Unit posix - Constants - Open flags - open/text381160
Node: Unit posix - Constants - Permission bits381379
Node: Unit posix - Constants - Permission bits - perm/irusr382450
Node: Unit posix - Constants - Permission bits - perm/iwusr382684
Node: Unit posix - Constants - Permission bits - perm/ixusr382980
Node: Unit posix - Constants - Permission bits - perm/irgrp383276
Node: Unit posix - Constants - Permission bits - perm/iwgrp383572
Node: Unit posix - Constants - Permission bits - perm/ixgrp383868
Node: Unit posix - Constants - Permission bits - perm/iroth384164
Node: Unit posix - Constants - Permission bits - perm/iwoth384460
Node: Unit posix - Constants - Permission bits - perm/ixoth384756
Node: Unit posix - Constants - Permission bits - perm/irwxu385052
Node: Unit posix - Constants - Permission bits - perm/irwxg385350
Node: Unit posix - Constants - Permission bits - perm/irwxo385648
Node: Unit posix - Constants - Permission bits - perm/isvtx385946
Node: Unit posix - Constants - Permission bits - perm/isuid386244
Node: Unit posix - Constants - Permission bits - perm/isgid386542
Node: Unit posix - Directories386778
Node: Unit posix - Directories - change-directory387362
Node: Unit posix - Directories - current-directory387657
Node: Unit posix - Directories - create-directory388125
Node: Unit posix - Directories - delete-directory388592
Node: Unit posix - Directories - directory388961
Node: Unit posix - Directories - directory?389480
Node: Unit posix - Directories - glob389843
Node: Unit posix - Directories - canonical-path390401
Node: Unit posix - Directories - set-root-directory!391697
Node: Unit posix - Pipes392136
Node: Unit posix - Pipes - call-with-input-pipe392718
Node: Unit posix - Pipes - call-with-output-pipe392923
Node: Unit posix - Pipes - close-input-pipe393492
Node: Unit posix - Pipes - close-output-pipe393732
Node: Unit posix - Pipes - create-pipe394180
Node: Unit posix - Pipes - open-input-pipe394584
Node: Unit posix - Pipes - open-output-pipe395074
Node: Unit posix - Pipes - pipe/buf395586
Node: Unit posix - Pipes - with-input-from-pipe395904
Node: Unit posix - Pipes - with-output-to-pipe396145
Node: Unit posix - Fifos397742
Node: Unit posix - Fifos - create-fifo397992
Node: Unit posix - Fifos - fifo?398345
Node: Unit posix - File descriptors and low-level I/O398591
Node: Unit posix - File descriptors and low-level I/O - duplicate-fileno399591
Node: Unit posix - File descriptors and low-level I/O - file-close400095
Node: Unit posix - File descriptors and low-level I/O - file-open400519
Node: Unit posix - File descriptors and low-level I/O - file-mkstemp401404
Node: Unit posix - File descriptors and low-level I/O - file-read402400
Node: Unit posix - File descriptors and low-level I/O - file-select403089
Node: Unit posix - File descriptors and low-level I/O - file-write404187
Node: Unit posix - File descriptors and low-level I/O - file-control404760
Node: Unit posix - File descriptors and low-level I/O - open-input-file*405295
Node: Unit posix - File descriptors and low-level I/O - open-output-file*405642
Node: Unit posix - File descriptors and low-level I/O - port->fileno406382
Node: Unit posix - Retrieving file attributes406799
Node: Unit posix - Retrieving file attributes - file-access-time408233
Node: Unit posix - Retrieving file attributes - file-change-time408484
Node: Unit posix - Retrieving file attributes - file-modification-time408808
Node: Unit posix - Retrieving file attributes - file-stat409431
Node: Unit posix - Retrieving file attributes - file-position410480
Node: Unit posix - Retrieving file attributes - file-size410901
Node: Unit posix - Retrieving file attributes - regular-file?411453
Node: Unit posix - Retrieving file attributes - file-owner411874
Node: Unit posix - Retrieving file attributes - file-permissions412283
Node: Unit posix - Retrieving file attributes - file-read-access?412820
Node: Unit posix - Retrieving file attributes - file-write-access?413145
Node: Unit posix - Retrieving file attributes - file-execute-access?413476
Node: Unit posix - Retrieving file attributes - stat-regular?414055
Node: Unit posix - Retrieving file attributes - stat-directory?414369
Node: Unit posix - Retrieving file attributes - stat-char-device?414684
Node: Unit posix - Retrieving file attributes - stat-block-device?415008
Node: Unit posix - Retrieving file attributes - stat-fifo?415329
Node: Unit posix - Retrieving file attributes - stat-symlink?415630
Node: Unit posix - Retrieving file attributes - stat-socket?415931
Node: Unit posix - Changing file attributes416519
Node: Unit posix - Changing file attributes - file-truncate416998
Node: Unit posix - Changing file attributes - set-file-position!417479
Node: Unit posix - Changing file attributes - change-file-mode418239
Node: Unit posix - Changing file attributes - change-file-owner418819
Node: Unit posix - Processes419287
Node: Unit posix - Processes - current-process-id419998
Node: Unit posix - Processes - parent-process-id420288
Node: Unit posix - Processes - process-group-id420639
Node: Unit posix - Processes - process-execute420991
Node: Unit posix - Processes - process-fork421917
Node: Unit posix - Processes - process-run422403
Node: Unit posix - Processes - process-signal423021
Node: Unit posix - Processes - process-wait423448
Node: Unit posix - Processes - process424312
Node: Unit posix - Processes - process*425375
Node: Unit posix - Processes - sleep426013
Node: Unit posix - Processes - create-session426405
Node: Unit posix - Hard and symbolic links426725
Node: Unit posix - Hard and symbolic links - symbolic-link?427203
Node: Unit posix - Hard and symbolic links - create-symbolic-link427535
Node: Unit posix - Hard and symbolic links - read-symbolic-link428000
Node: Unit posix - Hard and symbolic links - file-link428421
Node: Unit posix - Retrieving user & group information428751
Node: Unit posix - Retrieving user & group information - current-user-id429559
Node: Unit posix - Retrieving user & group information - current-effective-user-id429968
Node: Unit posix - Retrieving user & group information - user-information430498
Node: Unit posix - Retrieving user & group information - current-group-id431315
Node: Unit posix - Retrieving user & group information - current-effective-group-id431807
Node: Unit posix - Retrieving user & group information - group-information432385
Node: Unit posix - Retrieving user & group information - get-groups433067
Node: Unit posix - Changing user & group information433427
Node: Unit posix - Changing user & group information - set-groups!433916
Node: Unit posix - Changing user & group information - initialize-groups434354
Node: Unit posix - Changing user & group information - set-process-group-id!434937
Node: Unit posix - Record locking435389
Node: Unit posix - Record locking - file-lock435801
Node: Unit posix - Record locking - file-lock/blocking436394
Node: Unit posix - Record locking - file-test-lock436856
Node: Unit posix - Record locking - file-unlock437373
Node: Unit posix - Signal handling437672
Node: Unit posix - Signal handling - set-alarm!439448
Node: Unit posix - Signal handling - set-signal-handler!439853
Node: Unit posix - Signal handling - signal-handler440557
Node: Unit posix - Signal handling - set-signal-mask!440927
Node: Unit posix - Signal handling - signal-mask441406
Node: Unit posix - Signal handling - signal-masked?441742
Node: Unit posix - Signal handling - signal-mask!442112
Node: Unit posix - Signal handling - signal-unmask!442458
Node: Unit posix - Signal handling - signal/term442811
Node: Unit posix - Signal handling - signal/kill443065
Node: Unit posix - Signal handling - signal/int443317
Node: Unit posix - Signal handling - signal/hup443566
Node: Unit posix - Signal handling - signal/fpe443814
Node: Unit posix - Signal handling - signal/ill444062
Node: Unit posix - Signal handling - signal/segv444311
Node: Unit posix - Signal handling - signal/abrt444563
Node: Unit posix - Signal handling - signal/trap444816
Node: Unit posix - Signal handling - signal/quit445069
Node: Unit posix - Signal handling - signal/alrm445322
Node: Unit posix - Signal handling - signal/vtalrm445577
Node: Unit posix - Signal handling - signal/prof445836
Node: Unit posix - Signal handling - signal/io446089
Node: Unit posix - Signal handling - signal/urg446335
Node: Unit posix - Signal handling - signal/chld446583
Node: Unit posix - Signal handling - signal/cont446835
Node: Unit posix - Signal handling - signal/stop447088
Node: Unit posix - Signal handling - signal/tstp447341
Node: Unit posix - Signal handling - signal/pipe447594
Node: Unit posix - Signal handling - signal/xcpu447847
Node: Unit posix - Signal handling - signal/xfsz448100
Node: Unit posix - Signal handling - signal/usr1448353
Node: Unit posix - Signal handling - signal/usr2448606
Node: Unit posix - Signal handling - signal/winch448860
Node: Unit posix - Environment access449233
Node: Unit posix - Environment access - current-environment449599
Node: Unit posix - Environment access - setenv449946
Node: Unit posix - Environment access - unsetenv450411
Node: Unit posix - Memory mapped I/O450797
Node: Unit posix - Memory mapped I/O - memory-mapped-file?451255
Node: Unit posix - Memory mapped I/O - map-file-to-memory451618
Node: Unit posix - Memory mapped I/O - memory-mapped-file-pointer452714
Node: Unit posix - Memory mapped I/O - unmap-file-from-memory453174
Node: Unit posix - Date and time routines453789
Node: Unit posix - Date and time routines - seconds->local-time454437
Node: Unit posix - Date and time routines - local-time->seconds455590
Node: Unit posix - Date and time routines - local-timezone-abbreviation456128
Node: Unit posix - Date and time routines - seconds->string456573
Node: Unit posix - Date and time routines - seconds->utc-time457032
Node: Unit posix - Date and time routines - utc-time->seconds457455
Node: Unit posix - Date and time routines - time->string457939
Node: Unit posix - Raw exit458338
Node: Unit posix - Raw exit - _exit458560
Node: Unit posix - ERRNO values458927
Node: Unit posix - ERRNO values - errno/perm460123
Node: Unit posix - ERRNO values - errno/noent460311
Node: Unit posix - ERRNO values - errno/srch460548
Node: Unit posix - ERRNO values - errno/intr460783
Node: Unit posix - ERRNO values - errno/io461015
Node: Unit posix - ERRNO values - errno/noexec461245
Node: Unit posix - ERRNO values - errno/badf461483
Node: Unit posix - ERRNO values - errno/child461720
Node: Unit posix - ERRNO values - errno/nomem461958
Node: Unit posix - ERRNO values - errno/acces462197
Node: Unit posix - ERRNO values - errno/fault462438
Node: Unit posix - ERRNO values - errno/busy462678
Node: Unit posix - ERRNO values - errno/notdir462917
Node: Unit posix - ERRNO values - errno/isdir463160
Node: Unit posix - ERRNO values - errno/inval463402
Node: Unit posix - ERRNO values - errno/mfile463643
Node: Unit posix - ERRNO values - errno/nospc463884
Node: Unit posix - ERRNO values - errno/spipe464125
Node: Unit posix - ERRNO values - errno/pipe464365
Node: Unit posix - ERRNO values - errno/again464603
Node: Unit posix - ERRNO values - errno/rofs464842
Node: Unit posix - ERRNO values - errno/exist465080
Node: Unit posix - ERRNO values - errno/wouldblock465325
Node: Unit posix - Finding files465594
Node: Unit posix - Finding files - find-files465862
Node: Unit posix - Getting the hostname and system information467171
Node: Unit posix - Getting the hostname and system information - get-host-name467633
Node: Unit posix - Getting the hostname and system information - system-information468030
Node: Unit posix - Setting the file buffering mode468504
Node: Unit posix - Setting the file buffering mode - set-buffering-mode!468855
Node: Unit posix - Terminal ports469340
Node: Unit posix - Terminal ports - terminal-name469688
Node: Unit posix - Terminal ports - terminal-port?469992
Node: Unit posix - How Scheme procedures relate to UNIX C functions470307
Node: Unit posix - Windows specific notes473185
Node: Unit posix - Windows specific notes - Procedure Changes473860
Node: Unit posix - Windows specific notes - Unsupported Definitions474979
Node: Unit posix - Windows specific notes - Additional Definitions476385
Node: Unit posix - Windows specific notes - process-spawn477430
Node: Unit utils478321
Node: Unit utils - Environment Query478907
Node: Unit utils - Environment Query - apropos479195
Node: Unit utils - Environment Query - apropos-list479872
Node: Unit utils - Iterating over input lines and files480201
Node: Unit utils - Iterating over input lines and files - for-each-line480660
Node: Unit utils - Iterating over input lines and files - for-each-argv-line481289
Node: Unit utils - Executing shell commands with formatstring and error checking482070
Node: Unit utils - Executing shell commands with formatstring and error checking - system*482531
Node: Unit utils - Reading a file's contents482951
Node: Unit utils - Reading a file's contents - read-all483247
Node: Unit tcp483841
Node: Unit tcp - tcp-listen484780
Node: Unit tcp - tcp-listener?485297
Node: Unit tcp - tcp-close485563
Node: Unit tcp - tcp-accept485810
Node: Unit tcp - tcp-accept-ready?486757
Node: Unit tcp - tcp-listener-port487073
Node: Unit tcp - tcp-listener-fileno487447
Node: Unit tcp - tcp-connect487744
Node: Unit tcp - tcp-addresses489095
Node: Unit tcp - tcp-port-numbers489614
Node: Unit tcp - tcp-abandon-port490089
Node: Unit tcp - tcp-buffer-size490438
Node: Unit tcp - tcp-read-timeout491325
Node: Unit tcp - tcp-write-timeout491708
Node: Unit tcp - tcp-connect-timeout492100
Node: Unit tcp - tcp-accept-timeout492472
Node: Unit tcp - Example492830
Node: Unit lolevel493618
Node: Unit lolevel - Foreign pointers494294
Node: Unit lolevel - Foreign pointers - address->pointer495948
Node: Unit lolevel - Foreign pointers - allocate496314
Node: Unit lolevel - Foreign pointers - free496780
Node: Unit lolevel - Foreign pointers - null-pointer497203
Node: Unit lolevel - Foreign pointers - null-pointer?497535
Node: Unit lolevel - Foreign pointers - object->pointer497910
Node: Unit lolevel - Foreign pointers - pointer?498387
Node: Unit lolevel - Foreign pointers - pointer=?498738
Node: Unit lolevel - Foreign pointers - pointer->address499118
Node: Unit lolevel - Foreign pointers - pointer->object499490
Node: Unit lolevel - Foreign pointers - pointer-offset499869
Node: Unit lolevel - Foreign pointers - pointer-u8-ref500257
Node: Unit lolevel - Foreign pointers - pointer-s8-ref500633
Node: Unit lolevel - Foreign pointers - pointer-u16-ref501008
Node: Unit lolevel - Foreign pointers - pointer-s16-ref501399
Node: Unit lolevel - Foreign pointers - pointer-u32-ref501789
Node: Unit lolevel - Foreign pointers - pointer-s32-ref502181
Node: Unit lolevel - Foreign pointers - pointer-f32-ref502571
Node: Unit lolevel - Foreign pointers - pointer-f64-ref502952
Node: Unit lolevel - Foreign pointers - pointer-u8-set!503334
Node: Unit lolevel - Foreign pointers - pointer-s8-set!503763
Node: Unit lolevel - Foreign pointers - pointer-u16-set!504191
Node: Unit lolevel - Foreign pointers - pointer-s16-set!504636
Node: Unit lolevel - Foreign pointers - pointer-u32-set!505080
Node: Unit lolevel - Foreign pointers - pointer-s32-set!505526
Node: Unit lolevel - Foreign pointers - pointer-f32-set!505963
Node: Unit lolevel - Foreign pointers - pointer-f64-set!506414
Node: Unit lolevel - Foreign pointers - align-to-word506862
Node: Unit lolevel - Tagged pointers507274
Node: Unit lolevel - Tagged pointers - tag-pointer507728
Node: Unit lolevel - Tagged pointers - tagged-pointer?508098
Node: Unit lolevel - Tagged pointers - pointer-tag508521
Node: Unit lolevel - Extending procedures with data508925
Node: Unit lolevel - Extending procedures with data - extend-procedure509470
Node: Unit lolevel - Extending procedures with data - extended-procedure?510021
Node: Unit lolevel - Extending procedures with data - procedure-data510490
Node: Unit lolevel - Extending procedures with data - set-procedure-data!510991
Node: Unit lolevel - Data in unmanaged memory511719
Node: Unit lolevel - Data in unmanaged memory - object-evict512338
Node: Unit lolevel - Data in unmanaged memory - object-evict-to-location513684
Node: Unit lolevel - Data in unmanaged memory - object-evicted?514516
Node: Unit lolevel - Data in unmanaged memory - object-size514948
Node: Unit lolevel - Data in unmanaged memory - object-release515358
Node: Unit lolevel - Data in unmanaged memory - object-unevict515907
Node: Unit lolevel - Locatives516392
Node: Unit lolevel - Locatives - make-locative517398
Node: Unit lolevel - Locatives - make-weak-locative517868
Node: Unit lolevel - Locatives - locative?518369
Node: Unit lolevel - Locatives - locative-ref518687
Node: Unit lolevel - Locatives - locative-set!519103
Node: Unit lolevel - Locatives - locative->object519578
Node: Unit lolevel - Accessing toplevel variables519952
Node: Unit lolevel - Accessing toplevel variables - global-bound?520389
Node: Unit lolevel - Accessing toplevel variables - global-ref520788
Node: Unit lolevel - Accessing toplevel variables - global-set!521457
Node: Unit lolevel - Low-level data access521836
Node: Unit lolevel - Low-level data access - block-ref522625
Node: Unit lolevel - Low-level data access - block-set!523004
Node: Unit lolevel - Low-level data access - object-copy523510
Node: Unit lolevel - Low-level data access - make-record-instance523964
Node: Unit lolevel - Low-level data access - move-memory!524934
Node: Unit lolevel - Low-level data access - number-of-bytes525973
Node: Unit lolevel - Low-level data access - number-of-slots526412
Node: Unit lolevel - Low-level data access - record-instance?526874
Node: Unit lolevel - Low-level data access - record->vector527300
Node: Unit lolevel - Procedure-call- and variable reference hooks527649
Node: Unit lolevel - Procedure-call- and variable reference hooks - set-invalid-procedure-call-handler!528134
Node: Unit lolevel - Procedure-call- and variable reference hooks - unbound-variable-value529229
Node: Unit lolevel - Magic529952
Node: Unit lolevel - Magic - object-become!530209
Node: Unit lolevel - Magic - mutate-procedure531110
Node: Interface to external functions and variables531919
Node: Accessing external objects532597
Node: Accessing external objects - foreign-code533436
Node: Accessing external objects - foreign-value533953
Node: Accessing external objects - foreign-declare534422
Node: Accessing external objects - define-foreign-type534784
Node: Accessing external objects - define-foreign-variable536116
Node: Accessing external objects - define-foreign-record537502
Node: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME538975
Node: Accessing external objects - define-foreign-record - TYPENAME-SLOTNAME-set!539577
Node: Accessing external objects - define-foreign-record - constructor540694
Node: Accessing external objects - define-foreign-record - destructor541251
Node: Accessing external objects - define-foreign-record - rename541831
Node: Accessing external objects - define-foreign-enum543012
Node: Accessing external objects - foreign-lambda545750
Node: Accessing external objects - foreign-lambda*546272
Node: Accessing external objects - foreign-safe-lambda547211
Node: Accessing external objects - foreign-safe-lambda*547713
Node: Accessing external objects - foreign-primitive548239
Node: Foreign type specifiers549420
Node: Foreign type specifiers - scheme-object551701
Node: Foreign type specifiers - bool551942
Node: Foreign type specifiers - byte unsigned-byte552292
Node: Foreign type specifiers - char unsigned-char552547
Node: Foreign type specifiers - short unsigned-short552823
Node: Foreign type specifiers - int unsigned-int int32 unsigned-int32553133
Node: Foreign type specifiers - integer unsigned-integer integer32 unsigned-integer32 integer64553557
Node: Foreign type specifiers - long unsigned-long554068
Node: Foreign type specifiers - float double554462
Node: Foreign type specifiers - number554811
Node: Foreign type specifiers - symbol555234
Node: Foreign type specifiers - scheme-pointer555699
Node: Foreign type specifiers - nonnull-scheme-pointer556217
Node: Foreign type specifiers - c-pointer556650
Node: Foreign type specifiers - nonnull-c-pointer557088
Node: Foreign type specifiers - blob557377
Node: Foreign type specifiers - nonnull-blob557769
Node: Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector558101
Node: Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector558785
Node: Foreign type specifiers - c-string559516
Node: Foreign type specifiers - nonnull-c-string560231
Node: Foreign type specifiers - [nonnull-] c-string*560531
Node: Foreign type specifiers - [nonnull-] unsigned-c-string[*]561075
Node: Foreign type specifiers - c-string-list561436
Node: Foreign type specifiers - c-string-list*561854
Node: Foreign type specifiers - void562192
Node: Foreign type specifiers - ;const TYPE;562474
Node: Foreign type specifiers - ;enum NAME;562760
Node: Foreign type specifiers - ;c-pointer TYPE;563051
Node: Foreign type specifiers - ;nonnull-c-pointer TYPE;563373
Node: Foreign type specifiers - ;ref TYPE;563703
Node: Foreign type specifiers - ;struct NAME;564038
Node: Foreign type specifiers - ;template TYPE ARGTYPE ;;;;564490
Node: Foreign type specifiers - ;union NAME;564947
Node: Foreign type specifiers - ;instance CNAME SCHEMECLASS;565411
Node: Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;565933
Node: Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];566325
Node: Foreign type specifiers - Mappings566933
Node: Embedding569165
Node: Embedding - CHICKEN_parse_command_line570420
Node: Embedding - CHICKEN_initialize571032
Node: Embedding - CHICKEN_run571992
Node: Embedding - return-to-host573013
Node: Embedding - CHICKEN_eval573618
Node: Embedding - CHICKEN_eval_string574091
Node: Embedding - CHICKEN_eval_to_string574459
Node: Embedding - CHICKEN_eval_string_to_string574936
Node: Embedding - CHICKEN_apply575438
Node: Embedding - CHICKEN_apply_to_string575827
Node: Embedding - CHICKEN_read576264
Node: Embedding - CHICKEN_load576592
Node: Embedding - CHICKEN_get_error_message576898
Node: Embedding - CHICKEN_yield577287
Node: Embedding - CHICKEN_continue578966
Node: Embedding - CHICKEN_new_gc_root580555
Node: Embedding - CHICKEN_delete_gc_root581032
Node: Embedding - CHICKEN_gc_root_ref581330
Node: Embedding - CHICKEN_gc_root_set581638
Node: Embedding - CHICKEN_global_lookup582027
Node: Embedding - CHICKEN_global_ref582419
Node: Embedding - CHICKEN_global_set582762
Node: Callbacks583188
Node: Callbacks - define-external584403
Node: Callbacks - C_callback586079
Node: Callbacks - C_callback_adjust_stack586558
Node: Locations587668
Node: Locations - define-location588145
Node: Locations - let-location588500
Node: Locations - location588770
Node: Other support procedures590294
Node: Other support procedures - argc+argv590505
Node: C interface590878
Node: C interface - C_save592764
Node: C interface - C_restore592985
Node: C interface - C_fix593234
Node: C interface - C_make_character593435
Node: C interface - C_SCHEME_END_OF_LIST593682
Node: C interface - C_word C_SCHEME_END_OF_FILE593940
Node: C interface - C_word C_SCHEME_FALSE594217
Node: C interface - C_word C_SCHEME_TRUE594476
Node: C interface - C_string594765
Node: C interface - C_string2595012
Node: C interface - C_intern2595257
Node: C interface - C_intern3595503
Node: C interface - C_pair595768
Node: C interface - C_flonum595995
Node: C interface - C_int_to_num596222
Node: C interface - C_mpointer596463
Node: C interface - C_vector596700
Node: C interface - C_list596927
Node: C interface - C_alloc597335
Node: C interface - C_SIZEOF_LIST598342
Node: C interface - C_SIZEOF_STRING598570
Node: C interface - C_SIZEOF_VECTOR598812
Node: C interface - C_SIZEOF_INTERNED_SYMBOL599065
Node: C interface - C_SIZEOF_PAIR599343
Node: C interface - C_SIZEOF_FLONUM599575
Node: C interface - C_SIZEOF_POINTER599805
Node: C interface - C_SIZEOF_LOCATIVE600042
Node: C interface - C_SIZEOF_TAGGED_POINTER600290
Node: C interface - C_character_code600646
Node: C interface - C_unfix600900
Node: C interface - C_flonum_magnitude601119
Node: C interface - C_c_string601368
Node: C interface - C_num_to_int601600
Node: C interface - C_pointer_address601845
Node: C interface - C_header_size602311
Node: C interface - C_header_bits602545
Node: C interface - C_block_item602868
Node: C interface - C_u_i_car603357
Node: C interface - C_u_i_cdr603569
Node: C interface - C_data_pointer603857
Node: C interface - C_make_header604162
Node: C interface - C_mutate604478
Node: C interface - C_symbol_value605129
Node: C interface - C_gc_protect605570
Node: C interface - C_gc_unprotect606520
Node: C interface - C_pre_gc_hook606829
Node: C interface - C_post_gc_hook607644
Node: C interface - An example for simple calls to foreign code involving callbacks608544
Node: C interface - Notes;609609
Node: chicken-setup611841
Node: chicken-setup - Extension libraries612428
Node: chicken-setup - Installing extensions613592
Node: chicken-setup - Installing extensions - Installing extensions that use libraries615217
Node: chicken-setup - Creating extensions616304
Node: chicken-setup - Procedures and macros available in setup scripts616948
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension619418
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - syntax621540
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime622092
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - version622794
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - documentation623335
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - examples624120
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - exports625031
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - static625802
Node: chicken-setup - Procedures and macros available in setup scripts - install-extension - static-options626472
Node: chicken-setup - Procedures and macros available in setup scripts - install-program627189
Node: chicken-setup - Procedures and macros available in setup scripts - install-script627777
Node: chicken-setup - Procedures and macros available in setup scripts - run628379
Node: chicken-setup - Procedures and macros available in setup scripts - compile629017
Node: chicken-setup - Procedures and macros available in setup scripts - make629452
Node: chicken-setup - Procedures and macros available in setup scripts - patch630190
Node: chicken-setup - Procedures and macros available in setup scripts - copy-file630874
Node: chicken-setup - Procedures and macros available in setup scripts - move-file631401
Node: chicken-setup - Procedures and macros available in setup scripts - remove-file*631934
Node: chicken-setup - Procedures and macros available in setup scripts - find-library632424
Node: chicken-setup - Procedures and macros available in setup scripts - find-header633167
Node: chicken-setup - Procedures and macros available in setup scripts - try-compile633683
Node: chicken-setup - Procedures and macros available in setup scripts - create-directory634574
Node: chicken-setup - Procedures and macros available in setup scripts - chicken-prefix635115
Node: chicken-setup - Procedures and macros available in setup scripts - installation-prefix635620
Node: chicken-setup - Procedures and macros available in setup scripts - program-path636274
Node: chicken-setup - Procedures and macros available in setup scripts - setup-root-directory636950
Node: chicken-setup - Procedures and macros available in setup scripts - setup-build-directory637498
Node: chicken-setup - Procedures and macros available in setup scripts - setup-verbose-flag638111
Node: chicken-setup - Procedures and macros available in setup scripts - setup-install-flag638673
Node: chicken-setup - Procedures and macros available in setup scripts - required-chicken-version639245
Node: chicken-setup - Procedures and macros available in setup scripts - required-extension-version639916
Node: chicken-setup - Procedures and macros available in setup scripts - cross-chicken640819
Node: chicken-setup - Procedures and macros available in setup scripts - host-extension641352
Node: chicken-setup - Examples for extensions642063
Node: chicken-setup - chicken-setup reference647618
Node: chicken-setup - Windows notes651923
Node: chicken-setup - Security652948
Node: chicken-setup - Other modes of installation654058
Node: chicken-setup - Linking extensions statically655860
Node: Data representation657728
Node: Data representation - Immediate objects658205
Node: Data representation - Non-immediate objects659665
Node: Bugs and limitations663798
Node: FAQ664502
Node: FAQ - General665095
Node: FAQ - General - Why yet another Scheme implementation?666276
Node: FAQ - General - Why call it 'Chicken'?667485
Node: FAQ - General - What should I do if I find a bug?668147
Node: FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?668778
Node: FAQ - General - How does cond-expand know which features are registered in used units?669767
Node: FAQ - General - Why are constants defined by define-constant not honoured in case constructs?670680
Node: FAQ - General - How can I enable case sensitive reading/writing in user code?671435
Node: FAQ - General - How can I change match-error-control during compilation?672019
Node: FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?672547
Node: FAQ - General - How can I specialize a generic function method to match instances of every class?673564
Node: FAQ - General - Does CHICKEN support native threads?674435
Node: FAQ - General - Does CHICKEN support Unicode strings?675454
Node: FAQ - General - Why do I get an "Error; invalid syntax; ;;;" using 'match' and 'syntax-case'?677103
Node: FAQ - Platform specific677645
Node: FAQ - Platform specific - How do I generate a DLL under MS Windows ;tm; ?678542
Node: FAQ - Platform specific - How do I generate a GUI application under Windows;tm;?678954
Node: FAQ - Platform specific - Compiling very large files under Windows with the Microsoft C compiler fails with a message indicating insufficient heap space;679757
Node: FAQ - Platform specific - When I run csi inside an emacs buffer under Windows; nothing happens;680710
Node: FAQ - Platform specific - I load compiled code dynamically in a Windows GUI application and it crashes;681503
Node: FAQ - Platform specific - On Windows; csc;exe seems to be doing something wrong;682317
Node: FAQ - Platform specific - On Windows source and/or output filenames with embedded whitespace are not found;683060
Node: FAQ - Customization683654
Node: FAQ - Customization - How do I run custom startup code before the runtime-system is invoked?683984
Node: FAQ - Customization - How can I add compiled user passes?684923
Node: FAQ - Compiled macros686342
Node: FAQ - Compiled macros - Why is define-macro complaining about unbound variables?686878
Node: FAQ - Compiled macros - Why isn't load properly loading my library of macros?687425
Node: FAQ - Compiled macros - Why is include unable to load my hygienic macros?688026
Node: FAQ - Compiled macros - Why are macros not visible outside of the compilation unit in which they are defined?688632
Node: FAQ - Warnings and errors689358
Node: FAQ - Warnings and errors - Why does my program crash when I use callback functions ;from Scheme to C and back to Scheme again;?690505
Node: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_;;;_toplevel?691830
Node: FAQ - Warnings and errors - Why does the linker complain about a missing function _C_toplevel?692703
Node: FAQ - Warnings and errors - Why does my program crash when I compile a file with -unsafe or unsafe declarations?693541
Node: FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?694495
Node: FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?695716
Node: FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?697003
Node: FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?698121
Node: FAQ - Warnings and errors - How can I increase the size of the trace shown when runtime errors are detected?699497
Node: FAQ - Optimizations700238
Node: FAQ - Optimizations - How can I obtain smaller executables?700771
Node: FAQ - Optimizations - How can I obtain faster executables?701508
Node: FAQ - Optimizations - Which non-standard procedures are treated specially when the extended-bindings or usual-integrations declaration or compiler option is used?703487
Node: FAQ - Optimizations - Can I load compiled code at runtime?707154
Node: FAQ - Garbage collection707896
Node: FAQ - Garbage collection - Why does a loop that doesn't cons still trigger garbage collections?708275
Node: FAQ - Garbage collection - Why do finalizers not seem to work in simple cases in the interpeter?709655
Node: FAQ - Interpreter710745
Node: FAQ - Interpreter - Does CSI support history and autocompletion?711055
Node: FAQ - Interpreter - Does code loaded with load run compiled or interpreted?712225
Node: FAQ - Extensions712788
Node: FAQ - Extensions - How can I install Chicken eggs to a non-default location?713065
Node: FAQ - Extensions - Can I install chicken eggs as a non-root user?714196
Node: Acknowledgements714763
Node: Bibliography718537

End Tag Table
