This is sbcl.info, produced by makeinfo version 4.8 from sbcl.texinfo.

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* sbcl: (sbcl).           The Steel Bank Common Lisp compiler
END-INFO-DIR-ENTRY

     This manual is part of the SBCL software system. See the `README'
     file for more information.

     This manual is largely derived from the manual for the CMUCL
     system, which was produced at Carnegie Mellon University and later
     released into the public domain. This manual is in the public
     domain and is provided with absolutely no warranty. See the
     `COPYING' and `CREDITS' files for more information.


File: sbcl.info,  Node: Top,  Next: Getting Support and Reporting Bugs,  Up: (dir)

sbcl
****

     This manual is part of the SBCL software system. See the `README'
     file for more information.

     This manual is largely derived from the manual for the CMUCL
     system, which was produced at Carnegie Mellon University and later
     released into the public domain. This manual is in the public
     domain and is provided with absolutely no warranty. See the
     `COPYING' and `CREDITS' files for more information.

* Menu:

* Getting Support and Reporting Bugs::
* Introduction::
* Starting and Stopping::
* Compiler::
* Debugger::
* Efficiency::
* Beyond the ANSI Standard::
* Foreign Function Interface::
* Pathnames::
* Extensible Streams::
* Package Locks::
* Threading::
* Timers::
* Networking::
* Profiling::
* Contributed Modules::
* Concept Index::
* Function Index::
* Variable Index::
* Type Index::
* Colophon::


File: sbcl.info,  Node: Getting Support and Reporting Bugs,  Next: Introduction,  Prev: Top,  Up: Top

1 Getting Support and Reporting Bugs
************************************

* Menu:

* Volunteer Support::
* Commercial Support::
* Reporting Bugs::


File: sbcl.info,  Node: Volunteer Support,  Next: Commercial Support,  Up: Getting Support and Reporting Bugs

1.1 Volunteer Support
=====================

Your primary source of SBCL support should probably be the mailing list
*sbcl-help*: in addition to other users SBCL developers monitor this
list and are available for advice. As an anti-spam measure subcription
is required for posting:

       `https://lists.sourceforge.net/lists/listinfo/sbcl-help'

   Remember that the people answering your question are volunteers, so
you stand a much better chance of getting a good answer if you ask a
good question.

   Before sending mail, check the list archives at either

      
`http://sourceforge.net/mailarchive/forum.php?forum_name=sbcl-help'

   or

       `http://news.gmane.org/gmane.lisp.steel-bank.general'

   to see if your question has been answered already. Checking the bug
database is also worth it *Note Reporting Bugs::, to see if the issue
is already known.

   For general advice on asking good questions, see

       `http://www.catb.org/~esr/faqs/smart-questions.html'.


File: sbcl.info,  Node: Commercial Support,  Next: Reporting Bugs,  Prev: Volunteer Support,  Up: Getting Support and Reporting Bugs

1.2 Commercial Support
======================

There is no formal organization developing SBCL, but if you need a paid
support arrangement or custom SBCL development, we maintain the list of
companies and consultants below. Use it to identify service providers
with appropriate skills and interests, and contact them directly.

   The SBCL project cannot verify the accuracy of the information or the
competence of the people listed, and they have provided their own
blurbs below: you must make your own judgement of suitability from the
available information - refer to the links they provide, the CREDITS
file, mailing list archives, CVS commit messages, and so on. Please
feel free to ask for advice on the sbcl-help list.

*Christophe Rhodes*
     is a long-time SBCL developer, available for custom programming.

     Email: <csr21@cam.ac.uk>

*Steel Bank Studio Ltd*
     provides commercial SBCL support and custom development, is run by
     SBCL developer _Nikodemus Siivola_, and has another SBCL developer
     _Richard Kreuter_ as an affiliated consultant.

     Website: `http://sb-studio.net/'

     Email: <info@sb-studio.net>


File: sbcl.info,  Node: Reporting Bugs,  Prev: Commercial Support,  Up: Getting Support and Reporting Bugs

1.3 Reporting Bugs
==================

SBCL uses Launchpad to track bugs. The bug database is available at

       `https://bugs.launchpad.net/sbcl'

   Reporting bugs there requires registering at Launchpad. However, bugs
can also be reported on the mailing list *sbcl-bugs*, which is
moderated but does _not_ require subscribing.

   Simply send email to <sbcl-bugs@lists.sourceforge.net> and the bug
will be checked and added to Launchpad by SBCL maintainers.

1.3.1 How to Report Bugs Effectively
------------------------------------

Please include enough information in a bug report that someone reading
it can reproduce the problem, i.e. don't write

     Subject: apparent bug in PRINT-OBJECT (or *PRINT-LENGTH*?)
     PRINT-OBJECT doesn't seem to work with *PRINT-LENGTH*. Is this a bug?

   but instead

     Subject: apparent bug in PRINT-OBJECT (or *PRINT-LENGTH*?)
     In sbcl-1.2.3 running under OpenBSD 4.5 on my Alpha box, when
     I compile and load the file
        (DEFSTRUCT (FOO (:PRINT-OBJECT (LAMBDA (X Y)
                                         (LET ((*PRINT-LENGTH* 4))
                                           (PRINT X Y)))))
          X Y)
     then at the command line type
        (MAKE-FOO)
     the program loops endlessly instead of printing the object.

   A more in-depth discussion on reporting bugs effectively can be found
at

       `http://www.chiark.greenend.org.uk/~sgtatham/bugs.html'.

1.3.2 Signal Related Bugs
-------------------------

If you run into a signal related bug, you are getting fatal errors such
as `signal N is [un]blocked' or just hangs, and you want to send a
useful bug report then:

  1. Compile sbcl with ldb support (feature `:sb-ldb', see
     `base-target-features.lisp-expr') and change `#define QSHOW_SIGNAL
     0' to `#define QSHOW_SIGNAL 1' in `src/runtime/runtime.h'.

  2. Isolate a smallish test case, run it.

  3. If it just hangs kill it with sigabrt: `kill -ABRT <pidof sbcl>'.

  4. Print the backtrace from ldb by typing `ba'.

  5. Attach gdb: `gdb -p <pidof sbcl>' and get backtraces for all
     threads: `thread apply all ba'.

  6. If multiple threads are in play then still in gdb, try to get Lisp
     backtrace for all threads: `thread apply all
     call_backtrace_from_fp($ebp, 100)'. Substitute $ebp with $rbp on
     x86-64. The backtraces will appear in the stdout of the SBCL
     process.

  7. Send a report with the backtraces and the output (both stdout and
     stderr) produced by SBCL.

  8. Don't forget to include OS and SBCL version.

  9. If available include, information on outcome of the same test with
     other versions of SBCL, OS, ...


File: sbcl.info,  Node: Introduction,  Next: Starting and Stopping,  Prev: Getting Support and Reporting Bugs,  Up: Top

2 Introduction
**************

SBCL is a mostly-conforming implementation of the ANSI Common Lisp
standard. This manual focuses on behavior which is specific to SBCL,
not on behavior which is common to all implementations of ANSI Common
Lisp.

* Menu:

* ANSI Conformance::
* Extensions::
* Idiosyncrasies::
* Development Tools::
* More SBCL Information::
* More Common Lisp Information::
* History and Implementation of SBCL::


File: sbcl.info,  Node: ANSI Conformance,  Next: Extensions,  Up: Introduction

2.1 ANSI Conformance
====================

Essentially every type of non-conformance is considered a bug. (The
exceptions involve internal inconsistencies in the standard.)  *Note
Reporting Bugs::.


File: sbcl.info,  Node: Extensions,  Next: Idiosyncrasies,  Prev: ANSI Conformance,  Up: Introduction

2.2 Extensions
==============

SBCL comes with numerous extensions, some in core and some in modules
loadable with `require'. Unfortunately, not all of these extensions
have proper documentation yet.

*System Definition Tool*
     `asdf' is a flexible and popular protocol-oriented system
     definition tool by Daniel Barlow. *note the asdf manual:
     (asdf)Top, for more information.

*Third-party Extension Installation Tool*
     `asdf-install' is a tool that can be used to download and install
     third-party libraries and applications, automatically handling
     dependencies, etc.

*Foreign Function Interface*
     `sb-alien' package allows interfacing with C-code, loading shared
     object files, etc. *Note Foreign Function Interface::.

     `sb-grovel' can be used to partially automate generation of
     foreign function interface definitions. *Note sb-grovel::.

*Recursive Event Loop*
     SBCL provides a recursive event loop (`serve-event') for doing
     non-blocking IO on multiple streams without using threads.

*Metaobject Protocol*
     `sb-mop' package provides a metaobject protocol for the Common
     Lisp Object System as described in `Art of Metaobject Protocol'.

*Native Threads*
     SBCL has native threads on x86/Linux, capable of taking advantage
     of SMP on multiprocessor machines. *Note Threading::.

*Network Interface*
     `sb-bsd-sockets' is a low-level networking interface, providing
     both TCP and UDP sockets. *Note Networking::.

*Introspective Facilities*
     `sb-introspect' module offers numerous introspective extensions,
     including access to function lambda-lists and a cross referencing
     facility.

*Operating System Interface*
     `sb-ext' contains a number of functions for running external
     processes, accessing environment variables, etc.

     `sb-posix' module provides a lispy interface to standard POSIX
     facilities.

*Extensible Streams*
     `sb-gray' is an implementation of _Gray Streams_. *Note Gray
     Streams::.

     `sb-simple-streams' is an implementation of the _simple streams_
     API proposed by Franz Inc. *Note Simple Streams::.

*Profiling*
     `sb-profile' is a exact per-function profiler. *Note Deterministic
     Profiler::.

     `sb-sprof' is a statistical profiler, capable of call-graph
     generation and instruction level profiling, which also supports
     allocation profiling. *Note Statistical Profiler::.

*Customization Hooks*
     SBCL contains a number of extra-standard customization hooks that
     can be used to tweak the behaviour of the system. *Note
     Customization Hooks for Users::.

     `sb-aclrepl' provides an Allegro CL -style toplevel for SBCL, as
     an alternative to the classic CMUCL-style one. *Note sb-aclrepl::.

*CLTL2 Compatility Layer*
     `sb-cltl2' module provides `compiler-let' and environment access
     functionality described in `Common Lisp The Language, 2nd Edition'
     which were removed from the language during the ANSI
     standardization process.

*Executable Delivery*
     The `:executable' argument to *Note Function
     sb-ext:save-lisp-and-die:: can produce a `standalone' executable
     containing both an image of the current Lisp session and an SBCL
     runtime.

*Bitwise Rotation*
     `sb-rotate-byte' provides an efficient primitive for bitwise
     rotation of integers, an operation required by eg. numerous
     cryptographic algorithms, but not available as a primitive in ANSI
     Common Lisp. *Note sb-rotate-byte::.

*Test Harness*
     `sb-rt' module is a simple yet attractive regression and unit-test
     framework.

*MD5 Sums*
     `sb-md5' is an implementation of the MD5 message digest algorithm
     for Common Lisp, using the modular arithmetic optimizations
     provided by SBCL. *Note sb-md5::.



File: sbcl.info,  Node: Idiosyncrasies,  Next: Development Tools,  Prev: Extensions,  Up: Introduction

2.3 Idiosyncrasies
==================

The information in this section describes some of the ways that SBCL
deals with choices that the ANSI standard leaves to the implementation.

* Menu:

* Declarations::
* FASL Format::
* Compiler-only Implementation::
* Defining Constants::
* Style Warnings::


File: sbcl.info,  Node: Declarations,  Next: FASL Format,  Up: Idiosyncrasies

2.3.1 Declarations
------------------

Declarations are generally treated as assertions. This general
principle, and its implications, and the bugs which still keep the
compiler from quite satisfying this principle, are discussed in *Note
Declarations as Assertions::.


File: sbcl.info,  Node: FASL Format,  Next: Compiler-only Implementation,  Prev: Declarations,  Up: Idiosyncrasies

2.3.2 FASL Format
-----------------

SBCL fasl-format is binary compatible only with the exact SBCL version
it was generated with. While this is obviously suboptimal, it has
proven more robust than trying to maintain fasl compatibility across
versions: accidentally breaking things is far too easy, and can lead to
hard to diagnose bugs.

   The following snippet handles fasl recompilation automatically for
ASDF-based systems, and makes a good candidate for inclusion in the
user or system initialization file (*note Initialization Files::.)

     (require :asdf)

     ;;; If a fasl was stale, try to recompile and load (once).
     (defmethod asdf:perform :around ((o asdf:load-op)
                                      (c asdf:cl-source-file))
        (handler-case (call-next-method o c)
           ;; If a fasl was stale, try to recompile and load (once).
           (sb-ext:invalid-fasl ()
              (asdf:perform (make-instance 'asdf:compile-op) c)
              (call-next-method))))


File: sbcl.info,  Node: Compiler-only Implementation,  Next: Defining Constants,  Prev: FASL Format,  Up: Idiosyncrasies

2.3.3 Compiler-only Implementation
----------------------------------

SBCL is essentially a compiler-only implementation of Common Lisp.
That is, for all but a few special cases, `eval' creates a lambda
expression, calls `compile' on the lambda expression to create a
compiled function, and then calls `funcall' on the resulting function
object. This is explicitly allowed by the ANSI standard, but leads to
some oddities, e.g. collapsing `functionp' and `compiled-function-p'
into the same predicate.


File: sbcl.info,  Node: Defining Constants,  Next: Style Warnings,  Prev: Compiler-only Implementation,  Up: Idiosyncrasies

2.3.4 Defining Constants
------------------------

SBCL is quite strict about ANSI's definition of `defconstant'.  ANSI
says that doing `defconstant' of the same symbol more than once is
undefined unless the new value is `eql' to the old value.  Conforming
to this specification is a nuisance when the "constant" value is only
constant under some weaker test like `string=' or `equal'.

   It's especially annoying because, in SBCL, `defconstant' takes
effect not only at load time but also at compile time, so that just
compiling and loading reasonable code like
     (defconstant +foobyte+ '(1 4))
   runs into this undefined behavior. Many implementations of Common
Lisp try to help the programmer around this annoyance by silently
accepting the undefined code and trying to do what the programmer
probably meant.

   SBCL instead treats the undefined behavior as an error. Often such
code can be rewritten in portable ANSI Common Lisp which has the
desired behavior. E.g., the code above can be given an exactly defined
meaning by replacing `defconstant' either with `defparameter' or with a
customized macro which does the right thing, eg.
     (defmacro define-constant (name value &optional doc)
       `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
                           ,@(when doc (list doc))))
   or possibly along the lines of the `defconstant-eqx' macro used
internally in the implementation of SBCL itself. In circumstances where
this is not appropriate, the programmer can handle the condition type
`sb-ext:defconstant-uneql', and choose either the `continue' or `abort'
restart as appropriate.


File: sbcl.info,  Node: Style Warnings,  Prev: Defining Constants,  Up: Idiosyncrasies

2.3.5 Style Warnings
--------------------

SBCL gives style warnings about various kinds of perfectly legal code,
e.g.

   * `defmethod' without a preceding `defgeneric';

   * multiple `defun's of the same symbol in different units;

   * special variables not named in the conventional `*foo*' style, and
     lexical variables unconventionally named in the `*foo*' style


   This causes friction with people who point out that other ways of
organizing code (especially avoiding the use of `defgeneric') are just
as aesthetically stylish.  However, these warnings should be read not
as "warning, bad aesthetics detected, you have no style" but "warning,
this style keeps the compiler from understanding the code as well as
you might like." That is, unless the compiler warns about such
conditions, there's no way for the compiler to warn about some
programming errors which would otherwise be easy to overlook. (Related
bug: The warning about multiple `defun's is pointlessly annoying when
you compile and then load a function containing `defun' wrapped in
`eval-when', and ideally should be suppressed in that case, but still
isn't as of SBCL 0.7.6.)


File: sbcl.info,  Node: Development Tools,  Next: More SBCL Information,  Prev: Idiosyncrasies,  Up: Introduction

2.4 Development Tools
=====================

* Menu:

* Editor Integration::
* Language Reference::
* Generating Executables::


File: sbcl.info,  Node: Editor Integration,  Next: Language Reference,  Up: Development Tools

2.4.1 Editor Integration
------------------------

Though SBCL can be used running "bare", the recommended mode of
development is with an editor connected to SBCL, supporting not only
basic lisp editing (paren-matching, etc), but providing among other
features an integrated debugger, interactive compilation, and automated
documentation lookup.

   Currently "SLIME"(1) (Superior Lisp Interaction Mode for Emacs)
together with Emacs is recommended for use with SBCL, though other
options exist as well.

   SLIME can be downloaded from
`http://www.common-lisp.net/project/slime/'.

   ---------- Footnotes ----------

   (1) Historically, the ILISP package at `http://ilisp.cons.org/'
provided similar functionality, but it does not support modern SBCL
versions.


File: sbcl.info,  Node: Language Reference,  Next: Generating Executables,  Prev: Editor Integration,  Up: Development Tools

2.4.2 Language Reference
------------------------

"CLHS" (Common Lisp Hyperspec) is a hypertext version of the ANSI
standard, made freely available by _LispWorks_ - an invaluable
reference.

   See: `http://www.lispworks.com/reference/HyperSpec/index.html'


File: sbcl.info,  Node: Generating Executables,  Prev: Language Reference,  Up: Development Tools

2.4.3 Generating Executables
----------------------------

SBCL can generate stand-alone executables.  The generated executables
include the SBCL runtime itself, so no restrictions are placed on
program functionality.  For example, a deployed program can call
`compile' and `load', which requires the compiler to be present in the
executable.  For further information, *Note Function
sb-ext:save-lisp-and-die::.


File: sbcl.info,  Node: More SBCL Information,  Next: More Common Lisp Information,  Prev: Development Tools,  Up: Introduction

2.5 More SBCL Information
=========================

* Menu:

* SBCL Homepage::
* Online Documentation::
* Additional Documentation Files::
* Internals Documentation::


File: sbcl.info,  Node: SBCL Homepage,  Next: Online Documentation,  Up: More SBCL Information

2.5.1 SBCL Homepage
-------------------

The SBCL website at `http://www.sbcl.org/' has some general
information, plus links to mailing lists devoted to SBCL, and to
archives of these mailing lists. Subscribing to the mailing lists
`sbcl-help' and `sbcl-announce' is recommended: both are fairly
low-volume, and help you keep abrest with SBCL development.


File: sbcl.info,  Node: Online Documentation,  Next: Additional Documentation Files,  Prev: SBCL Homepage,  Up: More SBCL Information

2.5.2 Online Documentation
--------------------------

Documentation for non-ANSI extensions for various commands is available
online from the SBCL executable itself. The extensions for functions
which have their own command prompts (e.g. the debugger, and `inspect')
are documented in text available by typing `help' at their command
prompts. The extensions for functions which don't have their own
command prompt (such as `trace') are described in their documentation
strings, unless your SBCL was compiled with an option not to include
documentation strings, in which case the documentation strings are only
readable in the source code.


File: sbcl.info,  Node: Additional Documentation Files,  Next: Internals Documentation,  Prev: Online Documentation,  Up: More SBCL Information

2.5.3 Additional Documentation Files
------------------------------------

Besides this user manual both SBCL source and binary distributions
include some other SBCL-specific documentation files, which should be
installed along with this manual in on your system, eg. in
`/usr/local/share/doc/sbcl/'.

`COPYING'
     Licence and copyright summary.

`CREDITS'
     Authorship information on various parts of SBCL.

`INSTALL'
     Covers installing SBCL from both source and binary distributions on
     your system, and also has some installation related troubleshooting
     information.

`NEWS'
     Summarizes changes between various SBCL versions.



File: sbcl.info,  Node: Internals Documentation,  Prev: Additional Documentation Files,  Up: More SBCL Information

2.5.4 Internals Documentation
-----------------------------

If you're interested in the development of the SBCL system itself, then
subscribing to `sbcl-devel' is a good idea.

   SBCL internals documentation - besides comments in the source - is
currently maintained as a _wiki-like_ website:
`http://sbcl-internals.cliki.net/'.

   Some low-level information describing the programming details of the
conversion from CMUCL to SBCL is available in the
`doc/FOR-CMUCL-DEVELOPERS' file in the SBCL distribution, though it is
not installed by default.


File: sbcl.info,  Node: More Common Lisp Information,  Next: History and Implementation of SBCL,  Prev: More SBCL Information,  Up: Introduction

2.6 More Common Lisp Information
================================

* Menu:

* Internet Community::
* Third-party Libraries::
* Common Lisp Books::


File: sbcl.info,  Node: Internet Community,  Next: Third-party Libraries,  Up: More Common Lisp Information

2.6.1 Internet Community
------------------------

The Common Lisp internet community is fairly diverse:
`news://comp.lang.lisp' is fairly high volume newsgroup, but has a
rather poor signal/noise ratio. Various special interest mailing lists
and IRC tend to provide more content and less flames.
`http://www.lisp.org' and `http://www.cliki.net' contain numerous
pointers places in the net where lispers talks shop.


File: sbcl.info,  Node: Third-party Libraries,  Next: Common Lisp Books,  Prev: Internet Community,  Up: More Common Lisp Information

2.6.2 Third-party Libraries
---------------------------

For a wealth of information about free Common Lisp libraries and tools
we recommend checking out _CLiki_: `http://www.cliki.net/'.


File: sbcl.info,  Node: Common Lisp Books,  Prev: Third-party Libraries,  Up: More Common Lisp Information

2.6.3 Common Lisp Books
-----------------------

If you're not a programmer and you're trying to learn, many
introductory Lisp books are available. However, we don't have any
standout favorites. If you can't decide, try checking the Usenet
`news://comp.lang.lisp' FAQ for recent recommendations.

   If you are an experienced programmer in other languages but need to
learn about Common Lisp, some books stand out:

`Practical Common Lisp, by Peter Seibel'
     An excellent introduction to the language, covering both the basics
     and "advanced topics" like macros, CLOS, and packages. Available
     both in print format and on the web:
     `http://www.gigamonkeys.com/book/'.

`Paradigms Of Artificial Intelligence Programming, by Peter Norvig'
     Good information on general Common Lisp programming, and many
     nontrivial examples. Whether or not your work is AI, it's a very
     good book to look at.

`On Lisp, by Paul Graham'
     An in-depth treatment of macros, but not recommended as a first
     Common Lisp book, since it is slightly pre-ANSI so you need to be
     on your guard against non-standard usages, and since it doesn't
     really even try to cover the language as a whole, focusing solely
     on macros.  Downloadable from
     `http://www.paulgraham.com/onlisp.html'.

`Object-Oriented Programming In Common Lisp, by Sonya Keene'
     With the exception of `Practical Common Lisp' most introductory
     books don't emphasize CLOS. This one does. Even if you're very
     knowledgeable about object oriented programming in the abstract,
     it's worth looking at this book if you want to do any OO in Common
     Lisp.  Some abstractions in CLOS (especially multiple dispatch) go
     beyond anything you'll see in most OO systems, and there are a
     number of lesser differences as well. This book tends to help with
     the culture shock.

`Art Of Metaobject Programming, by Gregor Kiczales et al.'
     Currently to prime source of information on the Common Lisp
     Metaobject Protocol, which is supported by SBCL. Section 2
     (Chapers 5 and 6) are freely available at
     `http://www.lisp.org/mop/'.



File: sbcl.info,  Node: History and Implementation of SBCL,  Prev: More Common Lisp Information,  Up: Introduction

2.7 History and Implementation of SBCL
======================================

You can work productively with SBCL without knowing or understanding
anything about where it came from, how it is implemented, or how it
extends the ANSI Common Lisp standard. However, a little knowledge can
be helpful in order to understand error messages, to troubleshoot
problems, to understand why some parts of the system are better
debugged than others, and to anticipate which known bugs, known
performance problems, and missing extensions are likely to be fixed,
tuned, or added.

   SBCL is descended from CMUCL, which is itself descended from Spice
Lisp, including early implementations for the Mach operating system on
the IBM RT, back in the 1980s. Some design decisions from that time are
still reflected in the current implementation:

   * The system expects to be loaded into a fixed-at-compile-time
     location in virtual memory, and also expects the location of all
     of its heap storage to be specified at compile time.

   * The system overcommits memory, allocating large amounts of address
     space from the system (often more than the amount of virtual memory
     available) and then failing if ends up using too much of the
     allocated storage.

   * The system is implemented as a C program which is responsible for
     supplying low-level services and loading a Lisp `.core' file.


   SBCL also inherited some newer architectural features from CMUCL. The
most important is that on some architectures it has a generational
garbage collector ("GC"), which has various implications (mostly good)
for performance. These are discussed in another chapter, *Note
Efficiency::.

   SBCL has diverged from CMUCL in that SBCL is now essentially a
"compiler-only implementation" of Common Lisp. This is a change in
implementation strategy, taking advantage of the freedom "any of these
facilities might share the same execution strategy" guaranteed in the
ANSI specification section 3.1 ("Evaluation"). It does not mean SBCL
can't be used interactively, and in fact the change is largely invisible
to the casual user, since SBCL still can and does execute code
interactively by compiling it on the fly. (It is visible if you know how
to look, like using `compiled-function-p'; and it is visible in the way
that SBCL doesn't have many bugs which behave differently in
interpreted code than in compiled code.) What it means is that in SBCL,
the `eval' function only truly "interprets" a few easy kinds of forms,
such as symbols which are `boundp'. More complicated forms are
evaluated by calling `compile' and then calling `funcall' on the
returned result.

   The direct ancestor of SBCL is the x86 port of CMUCL. This port was
in some ways the most cobbled-together of all the CMUCL ports, since a
number of strange changes had to be made to support the register-poor
x86 architecture. Some things (like tracing and debugging) do not work
particularly well there. SBCL should be able to improve in these areas
(and has already improved in some other areas), but it takes a while.

   On the x86 SBCL - like the x86 port of CMUCL - uses a _conservative_
GC. This means that it doesn't maintain a strict separation between
tagged and untagged data, instead treating some untagged data (e.g. raw
floating point numbers) as possibly-tagged data and so not collecting
any Lisp objects that they point to. This has some negative
consequences for average time efficiency (though possibly no worse than
the negative consequences of trying to implement an exact GC on a
processor architecture as register-poor as the X86) and also has
potentially unlimited consequences for worst-case memory efficiency. In
practice, conservative garbage collectors work reasonably well, not
getting anywhere near the worst case. But they can occasionally cause
odd patterns of memory usage.

   The fork from CMUCL was based on a major rewrite of the system
bootstrap process. CMUCL has for many years tolerated a very unusual
"build" procedure which doesn't actually build the complete system from
scratch, but instead progressively overwrites parts of a running system
with new versions. This quasi-build procedure can cause various bizarre
bootstrapping hangups, especially when a major change is made to the
system. It also makes the connection between the current source code
and the current executable more tenuous than in other software systems
- it's easy to accidentally "build" a CMUCL system containing
characteristics not reflected in the current version of the source code.

   Other major changes since the fork from CMUCL include

   * SBCL has removed many CMUCL extensions, (e.g. IP networking,
     remote procedure call, Unix system interface, and X11 interface)
     from the core system. Most of these are available as contributed
     modules (distributed with sbcl) or third-party modules instead.

   * SBCL has deleted or deprecated some nonstandard features and code
     complexity which helped efficiency at the price of
     maintainability. For example, the SBCL compiler no longer
     implements memory pooling internally (and so is simpler and more
     maintainable, but generates more garbage and runs more slowly),
     and various block-compilation efficiency-increasing extensions to
     the language have been deleted or are no longer used in the
     implementation of SBCL itself.



File: sbcl.info,  Node: Starting and Stopping,  Next: Compiler,  Prev: Introduction,  Up: Top

3 Starting and Stopping
***********************

* Menu:

* Starting SBCL::
* Stopping SBCL::
* Command Line Options::
* Initialization Files::
* Initialization and Exit Hooks::


File: sbcl.info,  Node: Starting SBCL,  Next: Stopping SBCL,  Up: Starting and Stopping

3.1 Starting SBCL
=================

* Menu:

* Running from Shell::
* Running from Emacs::
* Shebang Scripts::


File: sbcl.info,  Node: Running from Shell,  Next: Running from Emacs,  Up: Starting SBCL

3.1.1 From Shell to Lisp
------------------------

To run SBCL type `sbcl' at the command line.

   You should end up in the toplevel "REPL" (read, eval, print -loop),
where you can interact with SBCL by typing expressions.

     $ sbcl
     This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
     More information about SBCL is available at <http://www.sbcl.org/>.

     SBCL is free software, provided as is, with absolutely no warranty.
     It is mostly in the public domain; some portions are provided under
     BSD-style licenses.  See the CREDITS and COPYING files in the
     distribution for more information.
     * (+ 2 2)

     4
     * (quit)
     $

   See also *Note Command Line Options:: and *Note Stopping SBCL::.


File: sbcl.info,  Node: Running from Emacs,  Next: Shebang Scripts,  Prev: Running from Shell,  Up: Starting SBCL

3.1.2 Running from Emacs
------------------------

To run SBCL as an inferior-lisp from Emacs in your `.emacs' do
something like:

     ;;; The SBCL binary and command-line arguments
     (setq inferior-lisp-program "/usr/local/bin/sbcl --noinform")

   For more information on using SBCL with Emacs, see *Note Editor
Integration::.


File: sbcl.info,  Node: Shebang Scripts,  Prev: Running from Emacs,  Up: Starting SBCL

3.1.3 Shebang Scripts
---------------------

Standard Unix tools that are interpreters follow a common command line
protocol that is necessary to work with "shebang scripts". SBCL supports
this via the `--script' command line option.

   Example file (`hello.lisp'):

     #!/usr/local/bin/sbcl --script
     (write-line "Hello, World!")

   Usage examples:

     $ ./hello.lisp
     Hello, World!

     $ sbcl --script hello.lisp
     Hello, World!


File: sbcl.info,  Node: Stopping SBCL,  Next: Command Line Options,  Prev: Starting SBCL,  Up: Starting and Stopping

3.2 Stopping SBCL
=================

* Menu:

* Quit::
* End of File::
* Saving a Core Image::
* Exit on Errors::


File: sbcl.info,  Node: Quit,  Next: End of File,  Up: Stopping SBCL

3.2.1 Quit
----------

SBCL can be stopped at any time by calling `sb-ext:quit', optionally
returning a specified numeric value to the calling process.  See notes
in *Note Threading:: about the interaction between this feature and
sessions.

 -- Function: sb-ext:quit &key recklessly-p unix-status
     Terminate the current Lisp. `*exit-hooks*' and pending
     unwind-protect cleanup forms are run unless `recklessly-p' is
     true. On UNIX-like systems, `unix-status' is used as the status
     code.


File: sbcl.info,  Node: End of File,  Next: Saving a Core Image,  Prev: Quit,  Up: Stopping SBCL

3.2.2 End of File
-----------------

By default SBCL also exits on end of input, caused either by user
pressing `Control-D' on an attached terminal, or end of input when
using SBCL as part of a shell pipeline.


File: sbcl.info,  Node: Saving a Core Image,  Next: Exit on Errors,  Prev: End of File,  Up: Stopping SBCL

3.2.3 Saving a Core Image
-------------------------

SBCL has the ability to save its state as a file for later execution.
This functionality is important for its bootstrapping process, and is
also provided as an extension to the user.

 -- Function: sb-ext:save-lisp-and-die core-file-name &key toplevel
          executable save-runtime-options purify root-structures
          environment-name
     Save a "core image", i.e. enough information to restart a Lisp
     process later in the same state, in the file of the specified name.
     Only global state is preserved: the stack is unwound in the
     process.

     The following `&key' arguments are defined:

    _`:toplevel'_
          The function to run when the created core file is resumed. The
              default function handles command line toplevel option
          processing      and runs the top level read-eval-print loop.
          This function returning      is equivalent to (SB-EXT:QUIT
          `:unix-status' 0) being called.

    _`:executable'_
          If true, arrange to combine the `sbcl' runtime and the core
          image      to create a standalone executable.  If false (the
          default), the      core image will not be executable on its
          own. Executable images      always behave as if they were
          passed the -noinform runtime option.

    _`:save-runtime-options'_
          If true, values of runtime options -dynamic-space-size and
           -control-stack-size that were used to start `sbcl' are
          stored in      the standalone executable, and restored when
          the executable is      run. This also inhibits normal runtime
          option processing, causing      all command line arguments to
          be passed to the toplevel.       Meaningless if `:executable'
          is `nil'.

    _`:purify'_
          If true (the default on cheneygc), do a purifying `gc' which
          moves all      dynamically allocated objects into static
          space. This takes      somewhat longer than the normal `gc'
          which is otherwise done, but      it's only done once, and
          subsequent GC's will be done less often      and will take
          less time in the resulting core file. See the `purify'
          function. This parameter has no effect on platforms using the
              generational garbage collector.

    _`:root-structures'_
          This should be a list of the main entry points in any newly
          loaded      systems. This need not be supplied, but locality
          and/or `gc' performance      may be better if they are.
          Meaningless if `:purify' is `nil'. See the      `purify'
          function.

    _`:environment-name'_
          This is also passed to the `purify' function when `:purify'
          is `t'.       (rarely used)


     The save/load process changes the values of some global variables:

    _`*standard-output*', `*debug-io*', etc._
          Everything related to open streams is necessarily changed,
          since     the `os' won't let us preserve a stream across save
          and load.

    _`*default-pathname-defaults*'_
          This is reinitialized to reflect the working directory where
          the     saved core is loaded.


     `save-lisp-and-die' interacts with `sb-alien:load-foreign-object:'
     see its documentation for details.

     On threaded platforms only a single thread may remain running after
     `sb-ext:*save-hooks*' have run. Applications using multiple
     threads can be `save-lisp-and-die' friendly by registering a
     save-hook that quits any additional threads, and an init-hook that
     restarts them.

     This implementation is not as polished and painless as you might
     like:
        * It corrupts the current Lisp image enough that the current
          process     needs to be killed afterwards. This can be worked
          around by forking     another process that saves the core.

        * There is absolutely no binary compatibility of core images
          between     different runtime support programs. Even runtimes
          built from the same     sources at different times are
          treated as incompatible for this     purpose.
     This isn't because we like it this way, but just because there
     don't seem to be good quick fixes for either limitation and no one
     has been sufficiently motivated to do lengthy fixes.

 -- Variable: sb-ext:*save-hooks*
     This is a list of functions which are called in an unspecified
     order before creating a saved core image. Unused by `sbcl' itself:
     reserved for user and applications.

   To facilitate distribution of SBCL applications using external
resources, the filesystem location of the SBCL core file being used is
available from Lisp.

 -- Variable: sb-ext:*core-pathname*
     The absolute pathname of the running `sbcl' core.


File: sbcl.info,  Node: Exit on Errors,  Prev: Saving a Core Image,  Up: Stopping SBCL

3.2.4 Exit on Errors
--------------------

SBCL can also be configured to exit if an unhandled error occurs, which
is mainly useful for acting as part of a shell pipeline; doing so under
most other circumstances would mean giving up large parts of the
flexibility and robustness of Common Lisp. See *Note Debugger Entry::.


File: sbcl.info,  Node: Command Line Options,  Next: Initialization Files,  Prev: Stopping SBCL,  Up: Starting and Stopping

3.3 Command Line Options
========================

Command line options can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.

   In order to understand the command line argument syntax for SBCL, it
is helpful to understand that the SBCL system is implemented as two
components, a low-level runtime environment written in C and a
higher-level system written in Common Lisp itself. Some command line
arguments are processed during the initialization of the low-level
runtime environment, some command line arguments are processed during
the initialization of the Common Lisp system, and any remaining command
line arguments are passed on to user code.

   The full, unambiguous syntax for invoking SBCL at the command line
is:

   `sbcl' RUNTIME-OPTION* `--end-runtime-options' TOPLEVEL-OPTION*
`--end-toplevel-options' USER-OPTIONS*

   For convenience, the `--end-runtime-options' and
`--end-toplevel-options' elements can be omitted. Omitting these
elements can be convenient when you are running the program
interactively, and you can see that no ambiguities are possible with
the option values you are using. Omitting these elements is probably a
bad idea for any batch file where any of the options are under user
control, since it makes it impossible for SBCL to detect erroneous
command line input, so that erroneous command line arguments will be
passed on to the user program even if they was intended for the runtime
system or the Lisp system.

* Menu:

* Runtime Options::
* Toplevel Options::


File: sbcl.info,  Node: Runtime Options,  Next: Toplevel Options,  Up: Command Line Options

3.3.1 Runtime Options
---------------------

`--core COREFILENAME'
     Run the specified Lisp core file instead of the default. Note that
     if the Lisp core file is a user-created core file, it may run a
     nonstandard toplevel which does not recognize the standard toplevel
     options.

`--dynamic-space-size MEGABYTES'
     Size of the dynamic space reserved on startup in megabytes. Default
     value is platform dependent.

`--control-stack-size MEGABYTES'
     Size of control stack reserved for each thread in megabytes.
     Default value is 2.

`--noinform'
     Suppress the printing of any banner or other informational message
     at startup. This makes it easier to write Lisp programs which work
     cleanly in Unix pipelines. See also the `--noprint' and
     `--disable-debugger' options.

`--disable-ldb'
     Disable the low-level debugger. Only effective if SBCL is compiled
     with LDB.

`--lose-on-corruption'
     There are some dangerous low level errors (for instance, control
     stack exhausted, memory fault) that (or whose handlers) can
     corrupt the image. By default SBCL prints a warning, then tries to
     continue and handle the error in Lisp, but this will not always
     work and SBCL may malfunction or even hang. With this option, upon
     encountering such an error SBCL will invoke ldb (if present and
     enabled) or else exit.

`--script FILENAME'
     As a runtime option this is equivalent to `--noinform'
     `--disable-ldb' `--lose-on-corruption' `--end-runtime-options'
     `--script' FILENAME. See the description of `--script' as a
     toplevel option below.

`--help'
     Print some basic information about SBCL, then exit.

`--version'
     Print SBCL's version information, then exit.


   In the future, runtime options may be added to control behaviour such
as lazy allocation of memory.

   Runtime options, including any -end-runtime-options option, are
stripped out of the command line before the Lisp toplevel logic gets a
chance to see it.


File: sbcl.info,  Node: Toplevel Options,  Prev: Runtime Options,  Up: Command Line Options

3.3.2 Toplevel Options
----------------------

`--sysinit FILENAME'
     Load filename instead of the default system initialization file
     (*note Initialization Files::.)

`--no-sysinit'
     Don't load a system-wide initialization file.  If this option is
     given, the `--sysinit' option is ignored.

`--userinit FILENAME'
     Load filename instead of the default user initialization file
     (*note Initialization Files::.)

`--no-userinit'
     Don't load a user initialization file.  If this option is given,
     the `--userinit' option is ignored.

`--eval COMMAND'
     After executing any initialization file, but before starting the
     read-eval-print loop on standard input, read and evaluate the
     command given. More than one `--eval' option can be used, and all
     will be read and executed, in the order they appear on the command
     line.

`--load FILENAME'
     This is equivalent to `--eval '(load "FILENAME")''. The special
     syntax is intended to reduce quoting headaches when invoking SBCL
     from shell scripts.

`--noprint'
     When ordinarily the toplevel "read-eval-print loop" would be exe-
     cuted, execute a "read-eval loop" instead, i.e. don't print a
     prompt and don't echo results. Combined with the `--noinform'
     runtime option, this makes it easier to write Lisp "scripts" which
     work cleanly in Unix pipelines.

`--disable-debugger'
     By default when SBCL encounters an error, it enters the builtin
     debugger, allowing interactive diagnosis and possible intercession.
     This option disables the debugger, causing errors to print a
     backtrace and exit with status 1 instead. When given, this option
     takes effect before loading of initialization files or processing
     `--eval' and `--load' options. See `sb-ext:disable-debugger' for
     details.  *Note Debugger Entry::.

`--script FILENAME'
     Implies `--no-userinit' `--no-sysinit' `--disable-debugger'
     `--end-toplevel-options'.

     Causes the system to load the specified file instead of entering
     the read-eval-print-loop, and exit afterwards. If the file begins
     with a shebang line, it is ignored.



File: sbcl.info,  Node: Initialization Files,  Next: Initialization and Exit Hooks,  Prev: Command Line Options,  Up: Starting and Stopping

3.4 Initialization Files
========================

SBCL processes initialization files with `read' and `eval', not `load';
hence initialization files can be used to set startup `*package*' and
`*readtable*', and for proclaiming a global optimization policy.

     *System Initialization File*

     Defaults to ``$SBCL_HOME'/sbclrc', or if that doesn't exist to
     `/etc/sbclrc'. Can be overridden with the command line option
     `--sysinit' or `--no-sysinit'.

     The system initialization file is intended for system
     administrators and software packagers to configure locations of
     installed third party modules, etc.

     *User Initialization File*

     Defaults to ``$HOME'/.sbclrc'. Can be overridden with the command
     line option `--userinit' or `--no-userinit'.

     The user initialization file is intended for personal
     customizations, such as loading certain modules at startup,
     defining convenience functions to use in the REPL, handling
     automatic recompilation of FASLs (*note FASL Format::), etc.


   Neither initialization file is required.


File: sbcl.info,  Node: Initialization and Exit Hooks,  Prev: Initialization Files,  Up: Starting and Stopping

3.5 Initialization and Exit Hooks
=================================

SBCL provides hooks into the system initialization and exit.

 -- Variable: sb-ext:*init-hooks*
     This is a list of functions which are called in an unspecified
     order when a saved core image starts up, after the system itself
     has been initialized. Unused by `sbcl' itself: reserved for user
     and applications.

 -- Variable: sb-ext:*exit-hooks*
     This is a list of functions which are called in an unspecified
     order when `sbcl' process exits. Unused by `sbcl' itself: reserved
     for user and applications. Using (QUIT `:recklessly-p' T), or
     calling exit(3) directly will circumvent these hooks.


File: sbcl.info,  Node: Compiler,  Next: Debugger,  Prev: Starting and Stopping,  Up: Top

4 Compiler
**********

This chapter will discuss most compiler issues other than efficiency,
including compiler error messages, the SBCL compiler's unusual approach
to type safety in the presence of type declarations, the effects of
various compiler optimization policies, and the way that inlining and
open coding may cause optimized code to differ from a naive
translation. Efficiency issues are sufficiently varied and separate
that they have their own chapter, *Note Efficiency::.

* Menu:

* Diagnostic Messages::
* Handling of Types::
* Compiler Policy::
* Compiler Errors::
* Open Coding and Inline Expansion::
* Interpreter::


File: sbcl.info,  Node: Diagnostic Messages,  Next: Handling of Types,  Up: Compiler

4.1 Diagnostic Messages
=======================

* Menu:

* Controlling Verbosity::
* Diagnostic Severity::
* Understanding Compiler Diagnostics::


File: sbcl.info,  Node: Controlling Verbosity,  Next: Diagnostic Severity,  Up: Diagnostic Messages

4.1.1 Controlling Verbosity
---------------------------

The compiler can be quite verbose in its diagnostic reporting, rather
more then some users would prefer - the amount of noise emitted can be
controlled, however.

   To control emission of compiler diagnostics (of any severity other
than `error': *note Diagnostic Severity::) use the
`sb-ext:muffle-conditions' and `sb-ext:unmuffle-conditions'
declarations, specifying the type of condition that is to be muffled
(the muffling is done using an associated `muffle-warning' restart).

   Global control:
     ;;; Muffle compiler-notes globally
     (declaim (sb-ext:muffle-conditions sb-ext:compiler-note))

   Local control:
     ;;; Muffle compiler-notes based on lexical scope
     (defun foo (x)
       (declare (optimize speed) (fixnum x)
                (sb-ext:muffle-conditions sb-ext:compiler-note))
       (values (* x 5) ; no compiler note from this
         (locally
           (declare (sb-ext:unmuffle-conditions sb-ext:compiler-note))
           ;; this one gives a compiler note
           (* x -5))))

 -- Declaration: sb-ext:muffle-conditions
     Syntax: type*

     Muffles the diagnostic messages that would be caused by
     compile-time signals of given types.

 -- Declaration: sb-ext:unmuffle-conditions
     Syntax: type*

     Cancels the effect of a previous `sb-ext:muffle-condition'
     declaration.

   Various details of _how_ the compiler messages are printed can be
controlled via the alist `sb-ext:*compiler-print-variable-alist*'.

 -- Variable: sb-ext:*compiler-print-variable-alist*
     an association list describing new bindings for special variables
     to be used by the compiler for error-reporting, etc. Eg.

           ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))

     The variables in the `car' positions are bound to the values in
     the `cdr' during the execution of some debug commands. When
     evaluating arbitrary expressions in the debugger, the normal
     values of the printer control variables are in effect.

     Initially empty, `*compiler-print-variable-alist*' is Typically
     used to specify bindings for printer control variables.

   For information about muffling warnings signaled outside of the
compiler, see *Note Customization Hooks for Users::.


File: sbcl.info,  Node: Diagnostic Severity,  Next: Understanding Compiler Diagnostics,  Prev: Controlling Verbosity,  Up: Diagnostic Messages

4.1.2 Diagnostic Severity
-------------------------

There are four levels of compiler diagnostic severity:

  1. error

  2. warning

  3. style warning

  4. note

   The first three levels correspond to condition classes which are
defined in the ANSI standard for Common Lisp and which have special
significance to the `compile' and `compile-file' functions.  These
levels of compiler error severity occur when the compiler handles
conditions of these classes.

   The fourth level of compiler error severity, _note_, corresponds to
the `sb-ext:compiler-note', and is used for problems which are too mild
for the standard condition classes, typically hints about how
efficiency might be improved. The `sb-ext:code-deletion-note', a
subtype of `compiler-note', is signalled when the compiler deletes
user-supplied code after proving that the code in question is
unreachable.

   Future work for SBCL includes expanding this hierarchy of types to
allow more fine-grained control over emission of diagnostic messages.

 -- Condition: sb-ext:compiler-note
     Class precedence list: `compiler-note, condition, t'

     Root of the hierarchy of conditions representing information
     discovered by the compiler that the user might wish to know, but
     which does not merit a `style-warning' (or any more serious
     condition).

 -- Condition: sb-ext:code-deletion-note
     Class precedence list: `code-deletion-note, compiler-note,
     condition, t'

     A condition type signalled when the compiler deletes code that the
     user has written, having proved that it is unreachable.


File: sbcl.info,  Node: Understanding Compiler Diagnostics,  Prev: Diagnostic Severity,  Up: Diagnostic Messages

4.1.3 Understanding Compile Diagnostics
---------------------------------------

The messages emitted by the compiler contain a lot of detail in a terse
format, so they may be confusing at first. The messages will be
illustrated using this example program:

     (defmacro zoq (x)
       `(roq (ploq (+ ,x 3))))

     (defun foo (y)
       (declare (symbol y))
       (zoq y))

   The main problem with this program is that it is trying to add `3'
to a symbol. Note also that the functions `roq' and `ploq' aren't
defined anywhere.

* Menu:

* The Parts of a Compiler Diagnostic::
* The Original and Actual Source::
* The Processing Path::


File: sbcl.info,  Node: The Parts of a Compiler Diagnostic,  Next: The Original and Actual Source,  Up: Understanding Compiler Diagnostics

4.1.3.1 The Parts of a Compiler Diagnostic
..........................................

When processing this program, the compiler will produce this warning:

     ; file: /tmp/foo.lisp
     ; in: DEFUN FOO
     ;     (ZOQ Y)
     ; --> ROQ PLOQ
     ; ==>
     ;   (+ Y 3)
     ;
     ; caught WARNING:
     ;   Asserted type NUMBER conflicts with derived type (VALUES SYMBOL &OPTIONAL).

   In this example we see each of the six possible parts of a compiler
diagnostic:

  1. `file: /tmp/foo.lisp' This is the name of the file that the
     compiler read the relevant code from.  The file name is displayed
     because it may not be immediately obvious when there is an error
     during compilation of a large system, especially when
     `with-compilation-unit' is used to delay undefined warnings.

  2. `in: DEFUN FOO' This is the definition top level form responsible
     for the diagnostic. It is obtained by taking the first two
     elements of the enclosing form whose first element is a symbol
     beginning with "`def'". If there is no such enclosing "`def'" form,
     then the outermost form is used. If there are multiple `def'
     forms, then they are all printed from the outside in, separated by
     `=>''s. In this example, the problem was in the `defun' for `foo'.

  3. `(ZOQ Y)' This is the "original source" form responsible for the
     diagnostic. Original source means that the form directly appeared
     in the original input to the compiler, i.e. in the lambda passed to
     `compile' or in the top level form read from the source file. In
     this example, the expansion of the `zoq' macro was responsible for
     the message.

  4. `--> ROQ PLOQ' This is the "processing path" that the compiler
     used to produce the code that caused the message to be emitted.
     The processing path is a representation of the evaluated forms
     enclosing the actual source that the compiler encountered when
     processing the original source. The path is the first element of
     each form, or the form itself if the form is not a list. These
     forms result from the expansion of macros or source-to-source
     transformation done by the compiler. In this example, the
     enclosing evaluated forms are the calls to `roq' and `ploq'. These
     calls resulted from the expansion of the `zoq' macro.

  5. `==> (+ Y 3)' This is the "actual source" responsible for the
     diagnostic. If the actual source appears in the explanation, then
     we print the next enclosing evaluated form, instead of printing the
     actual source twice. (This is the form that would otherwise have
     been the last form of the processing path.) In this example, the
     problem is with the evaluation of the reference to the variable
     `y'.

  6. `caught WARNING: Asserted type NUMBER conflicts with derived type
     (VALUES SYMBOL &OPTIONAL).'  This is the "explanation" of the
     problem. In this example, the problem is that, while the call to
     `+' requires that its arguments are all of type `number', the
     compiler has derived that `y' will evaluate to a `symbol'.  Note
     that `(VALUES SYMBOL &OPTIONAL)' expresses that `y' evaluates to
     precisely one value.


   Note that each part of the message is distinctively marked:

   *  `file:' and `in:' mark the file and definition, respectively.

   * The original source is an indented form with no prefix.

   * Each line of the processing path is prefixed with `-->'

   * The actual source form is indented like the original source, but is
     marked by a preceding `==>' line.

   * The explanation is prefixed with the diagnostic severity, which
     can be `caught ERROR:', `caught WARNING:', `caught
     STYLE-WARNING:', or `note:'.


   Each part of the message is more specific than the preceding one. If
consecutive messages are for nearby locations, then the front part of
the messages would be the same. In this case, the compiler omits as
much of the second message as in common with the first. For example:

     ; file: /tmp/foo.lisp
     ; in: DEFUN FOO
     ;     (ZOQ Y)
     ; --> ROQ
     ; ==>
     ;   (PLOQ (+ Y 3))
     ;
     ; caught STYLE-WARNING:
     ;   undefined function: PLOQ

     ; ==>
     ;   (ROQ (PLOQ (+ Y 3)))
     ;
     ; caught STYLE-WARNING:
     ;   undefined function: ROQ

   In this example, the file, definition and original source are
identical for the two messages, so the compiler omits them in the
second message. If consecutive messages are entirely identical, then
the compiler prints only the first message, followed by: `[Last message
occurs REPEATS times]' where REPEATS is the number of times the message
was given.

   If the source was not from a file, then no file line is printed. If
the actual source is the same as the original source, then the
processing path and actual source will be omitted. If no forms
intervene between the original source and the actual source, then the
processing path will also be omitted.


File: sbcl.info,  Node: The Original and Actual Source,  Next: The Processing Path,  Prev: The Parts of a Compiler Diagnostic,  Up: Understanding Compiler Diagnostics

4.1.3.2 The Original and Actual Source
......................................

The _original source_ displayed will almost always be a list. If the
actual source for an message is a symbol, the original source will be
the immediately enclosing evaluated list form. So even if the offending
symbol does appear in the original source, the compiler will print the
enclosing list and then print the symbol as the actual source (as
though the symbol were introduced by a macro.)

   When the _actual source_ is displayed (and is not a symbol), it will
always be code that resulted from the expansion of a macro or a
source-to-source compiler optimization. This is code that did not
appear in the original source program; it was introduced by the
compiler.

   Keep in mind that when the compiler displays a source form in an
diagnostic message, it always displays the most specific (innermost)
responsible form. For example, compiling this function

     (defun bar (x)
       (let (a)
         (declare (fixnum a))
         (setq a (foo x))
         a))

   gives this error message

     ; file: /tmp/foo.lisp
     ; in: DEFUN BAR
     ;     (LET (A)
     ;     (DECLARE (FIXNUM A))
     ;     (SETQ A (FOO X))
     ;     A)
     ;
     ; caught WARNING:
     ;   Asserted type FIXNUM conflicts with derived type (VALUES NULL &OPTIONAL).

   This message is not saying "there is a problem somewhere in this
`let'" - it is saying that there is a problem with the `let' itself. In
this example, the problem is that `a''s `nil' initial value is not a
`fixnum'.


File: sbcl.info,  Node: The Processing Path,  Prev: The Original and Actual Source,  Up: Understanding Compiler Diagnostics

4.1.3.3 The Processing Path
...........................

The processing path is mainly useful for debugging macros, so if you
don't write macros, you can probably ignore it. Consider this example:

     (defun foo (n)
       (dotimes (i n *undefined*)))

   Compiling results in this error message:

     ; in: DEFUN FOO
     ;     (DOTIMES (I N *UNDEFINED*))
     ; --> DO BLOCK LET TAGBODY RETURN-FROM
     ; ==>
     ;   (PROGN *UNDEFINED*)
     ;
     ; caught WARNING:
     ;   undefined variable: *UNDEFINED*

   Note that `do' appears in the processing path. This is because
`dotimes' expands into:

     (do ((i 0 (1+ i)) (#:g1 n))
         ((>= i #:g1) *undefined*)
       (declare (type unsigned-byte i)))

   The rest of the processing path results from the expansion of `do':

     (block nil
       (let ((i 0) (#:g1 n))
         (declare (type unsigned-byte i))
         (tagbody (go #:g3)
           #:g2    (psetq i (1+ i))
           #:g3    (unless (>= i #:g1) (go #:g2))
           (return-from nil (progn *undefined*)))))

   In this example, the compiler descended into the `block', `let',
`tagbody' and `return-from' to reach the `progn' printed as the actual
source. This is a place where the "actual source appears in
explanation" rule was applied. The innermost actual source form was the
symbol `*undefined*' itself, but that also appeared in the explanation,
so the compiler backed out one level.


File: sbcl.info,  Node: Handling of Types,  Next: Compiler Policy,  Prev: Diagnostic Messages,  Up: Compiler

4.2 Handling of Types
=====================

One of the most important features of the SBCL compiler (similar to the
original CMUCL compiler, also known as "Python") is its fairly
sophisticated understanding of the Common Lisp type system and its
conservative approach to the implementation of type declarations.

   These two features reward the use of type declarations throughout
development, even when high performance is not a concern. Also, as
discussed in the chapter on performance (*note Efficiency::), the use
of appropriate type declarations can be very important for performance
as well.

   The SBCL compiler also has a greater knowledge of the Common Lisp
type system than other compilers. Support is incomplete only for types
involving the `satisfies' type specifier.

* Menu:

* Declarations as Assertions::
* Precise Type Checking::
* Getting Existing Programs to Run::
* Implementation Limitations::


File: sbcl.info,  Node: Declarations as Assertions,  Next: Precise Type Checking,  Up: Handling of Types

4.2.1 Declarations as Assertions
--------------------------------

The SBCL compiler treats type declarations differently from most other
Lisp compilers. Under default compilation policy the compiler doesn't
blindly believe type declarations, but considers them assertions about
the program that should be checked: all type declarations that have not
been proven to always hold are asserted at runtime.

     _Remaining bugs in the compiler's handling of types unfortunately
     provide some exceptions to this rule, see *Note Implementation
     Limitations::._

   CLOS slot types form a notable exception. Types declared using the
`:type' slot option in `defclass' are asserted if and only if the class
was defined in _safe code_ and the slot access location is in _safe
code_ as well. This laxness does not pose any internal consistency
issues, as the CLOS slot types are not available for the type
inferencer, nor do CLOS slot types provide any efficiency benefits.

   There are three type checking policies available in SBCL, selectable
via `optimize' declarations.

*Full Type Checks*
     All declarations are considered assertions to be checked at
     runtime, and all type checks are precise. The default compilation
     policy provides full type checks.

     Used when `(or (>= safety 2) (>= safety speed 1))'.

*Weak Type Checks*
     Declared types may be simplified into faster to check supertypes:
     for example, `(or (integer -17 -7) (integer 7 17))' is simplified
     into `(integer -17 17)'.

     *Note*: it is relatively easy to corrupt the heap when weak type
     checks are used if the program contains type-errors.

     Used when `(and (< safety 2) (< safety speed))'

*No Type Checks*
     All declarations are believed without assertions. Also disables
     argument count and array bounds checking.

     *Note*: any type errors in code where type checks are not
     performed are liable to corrupt the heap.

     Used when `(= safety 0)'.



File: sbcl.info,  Node: Precise Type Checking,  Next: Getting Existing Programs to Run,  Prev: Declarations as Assertions,  Up: Handling of Types

4.2.2 Precise Type Checking
---------------------------

Precise checking means that the check is done as though `typep' had
been called with the exact type specifier that appeared in the
declaration.

   If a variable is declared to be `(integer 3 17)' then its value must
always be an integer between `3' and `17'. If multiple type
declarations apply to a single variable, then all the declarations must
be correct; it is as though all the types were intersected producing a
single `and' type specifier.

   To gain maximum benefit from the compiler's type checking, you should
always declare the types of function arguments and structure slots as
precisely as possible. This often involves the use of `or', `member',
and other list-style type specifiers.


File: sbcl.info,  Node: Getting Existing Programs to Run,  Next: Implementation Limitations,  Prev: Precise Type Checking,  Up: Handling of Types

4.2.3 Getting Existing Programs to Run
--------------------------------------

Since SBCL's compiler does much more comprehensive type checking than
most Lisp compilers, SBCL may detect type errors in programs that have
been debugged using other compilers. These errors are mostly incorrect
declarations, although compile-time type errors can find actual bugs if
parts of the program have never been tested.

   Some incorrect declarations can only be detected by run-time type
checking. It is very important to initially compile a program with full
type checks (high `safety' optimization) and then test this safe
version. After the checking version has been tested, then you can
consider weakening or eliminating type checks.  _This applies even to
previously debugged programs,_ because the SBCL compiler does much more
type inference than other Common Lisp compilers, so an incorrect
declaration can do more damage.

   The most common problem is with variables whose constant initial
value doesn't match the type declaration. Incorrect constant initial
values will always be flagged by a compile-time type error, and they are
simple to fix once located. Consider this code fragment:

     (prog (foo)
       (declare (fixnum foo))
       (setq foo ...)
       ...)

   Here `foo' is given an initial value of `nil', but is declared to be
a `fixnum'.  Even if it is never read, the initial value of a variable
must match the declared type.  There are two ways to fix this problem.
Change the declaration

     (prog (foo)
       (declare (type (or fixnum null) foo))
       (setq foo ...)
       ...)

   or change the initial value

     (prog ((foo 0))
       (declare (fixnum foo))
       (setq foo ...)
       ...)

   It is generally preferable to change to a legal initial value rather
than to weaken the declaration, but sometimes it is simpler to weaken
the declaration than to try to make an initial value of the appropriate
type.

   Another declaration problem occasionally encountered is incorrect
declarations on `defmacro' arguments. This can happen when a function
is converted into a macro. Consider this macro:

     (defmacro my-1+ (x)
       (declare (fixnum x))
       `(the fixnum (1+ ,x)))

   Although legal and well-defined Common Lisp code, this meaning of
this definition is almost certainly not what the writer intended. For
example, this call is illegal:

     (my-1+ (+ 4 5))

   This call is illegal because the argument to the macro is `(+ 4 5)',
which is a `list', not a `fixnum'.  Because of macro semantics, it is
hardly ever useful to declare the types of macro arguments.  If you
really want to assert something about the type of the result of
evaluating a macro argument, then put a `the' in the expansion:

     (defmacro my-1+ (x)
       `(the fixnum (1+ (the fixnum ,x))))

   In this case, it would be stylistically preferable to change this
macro back to a function and declare it inline.

   Some more subtle problems are caused by incorrect declarations that
can't be detected at compile time.  Consider this code:

     (do ((pos 0 (position #\a string :start (1+ pos))))
       ((null pos))
       (declare (fixnum pos))
       ...)

   Although `pos' is almost always a `fixnum', it is `nil' at the end
of the loop. If this example is compiled with full type checks (the
default), then running it will signal a type error at the end of the
loop. If compiled without type checks, the program will go into an
infinite loop (or perhaps `position' will complain because `(1+ nil)'
isn't a sensible start.) Why? Because if you compile without type
checks, the compiler just quietly believes the type declaration. Since
the compiler believes that `pos' is always a `fixnum', it believes that
`pos' is never `nil', so `(null pos)' is never true, and the loop exit
test is optimized away. Such errors are sometimes flagged by unreachable
code notes, but it is still important to initially compile and test any
system with full type checks, even if the system works fine when
compiled using other compilers.

   In this case, the fix is to weaken the type declaration to `(or
fixnum null)' (1).

   Note that there is usually little performance penalty for weakening a
declaration in this way. Any numeric operations in the body can still
assume that the variable is a `fixnum', since `nil' is not a legal
numeric argument. Another possible fix would be to say:

     (do ((pos 0 (position #\a string :start (1+ pos))))
         ((null pos))
       (let ((pos pos))
         (declare (fixnum pos))
         ...))

   This would be preferable in some circumstances, since it would allow
a non-standard representation to be used for the local `pos' variable
in the loop body.

   ---------- Footnotes ----------

   (1) Actually, this declaration is unnecessary in SBCL, since it
already knows that `position' returns a non-negative `fixnum' or `nil'.


File: sbcl.info,  Node: Implementation Limitations,  Prev: Getting Existing Programs to Run,  Up: Handling of Types

4.2.4 Implementation Limitations
--------------------------------

Ideally, the compiler would consider _all_ type declarations to be
assertions, so that adding type declarations to a program, no matter
how incorrect they might be, would _never_ cause undefined behavior.
However, the compiler is known to fall short of this goal in two areas:

   * _Proclaimed_ constraints on argument and result types of a
     function are supposed to be checked by the function. If the
     function type is proclaimed before function definition, type
     checks are inserted by the compiler, but the standard allows the
     reversed order, in which case the compiler will trust the
     declaration.

   * The compiler cannot check types of an unknown number of values; if
     the number of generated values is unknown, but the number of
     consumed is known, only consumed values are checked.

     For example,

          (defun foo (x)
            (the integer (bar x)))

     causes the following compiler diagnostic to be emitted:

          ; note: type assertion too complex to check:
          ;  (VALUES INTEGER &REST T).

     A partial workaround is instead write:

          (defun foo (x)
            (the (values integer &optional) (bar x)))


   These are important issues, but are not necessarily easy to fix, so
they may, alas, remain in the system for a while.


File: sbcl.info,  Node: Compiler Policy,  Next: Compiler Errors,  Prev: Handling of Types,  Up: Compiler

4.3 Compiler Policy
===================

Compiler policy is controlled by the `optimize' declaration, supporting
all ANSI optimization qualities (`debug', `safety', `space', and
`speed').(1)

   For effects of various optimization qualities on type-safety and
debuggability see *Note Declarations as Assertions:: and *Note Debugger
Policy Control::.

   Ordinarily, when the `speed' quality is high, the compiler emits
notes to notify the programmer about its inability to apply various
optimizations. For selective muffling of these notes *Note Controlling
Verbosity::.

   The value of `space' mostly influences the compiler's decision
whether to inline operations, which tend to increase the size of
programs. Use the value `0' with caution, since it can cause the
compiler to inline operations so indiscriminately that the net effect
is to slow the program by causing cache misses or even swapping.

   ---------- Footnotes ----------

   (1) A deprecated extension `sb-ext:inhibit-warnings' is still
supported, but liable to go away at any time.


File: sbcl.info,  Node: Compiler Errors,  Next: Open Coding and Inline Expansion,  Prev: Compiler Policy,  Up: Compiler

4.4 Compiler Errors
===================

* Menu:

* Type Errors at Compile Time::
* Errors During Macroexpansion::
* Read Errors::


File: sbcl.info,  Node: Type Errors at Compile Time,  Next: Errors During Macroexpansion,  Up: Compiler Errors

4.4.1 Type Errors at Compile Time
---------------------------------

If the compiler can prove at compile time that some portion of the
program cannot be executed without a type error, then it will give a
warning at compile time.

   It is possible that the offending code would never actually be
executed at run-time due to some higher level consistency constraint
unknown to the compiler, so a type warning doesn't always indicate an
incorrect program.

   For example, consider this code fragment:

     (defun raz (foo)
       (let ((x (case foo
                   (:this 13)
                   (:that 9)
                   (:the-other 42))))
         (declare (fixnum x))
         (foo x)))

   Compilation produces this warning:

     ; in: DEFUN RAZ
     ;     (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
     ; --> LET COND IF COND IF COND IF
     ; ==>
     ;   (COND)
     ;
     ; caught WARNING:
     ;   This is not a FIXNUM:
     ;   NIL

   In this case, the warning means that if `foo' isn't any of `:this',
`:that' or `:the-other', then `x' will be initialized to `nil', which
the `fixnum' declaration makes illegal. The warning will go away if
`ecase' is used instead of `case', or if `:the-other' is changed to `t'.

   This sort of spurious type warning happens moderately often in the
expansion of complex macros and in inline functions. In such cases,
there may be dead code that is impossible to correctly execute. The
compiler can't always prove this code is dead (could never be
executed), so it compiles the erroneous code (which will always signal
an error if it is executed) and gives a warning.


File: sbcl.info,  Node: Errors During Macroexpansion,  Next: Read Errors,  Prev: Type Errors at Compile Time,  Up: Compiler Errors

4.4.2 Errors During Macroexpansion
----------------------------------

The compiler handles errors that happen during macroexpansion, turning
them into compiler errors. If you want to debug the error (to debug a
macro), you can set `*break-on-signals*' to `error'. For example, this
definition:

     (defun foo (e l)
       (do ((current l (cdr current))
            ((atom current) nil))
           (when (eq (car current) e) (return current))))

   gives this error:

     ; in: DEFUN FOO
     ;     (DO ((CURRENT L (CDR CURRENT))
     ;        ((ATOM CURRENT) NIL))
     ;       (WHEN (EQ (CAR CURRENT) E) (RETURN CURRENT)))
     ;
     ; caught ERROR:
     ;   (in macroexpansion of (DO # #))
     ;   (hint: For more precise location, try *BREAK-ON-SIGNALS*.)
     ;   DO step variable is not a symbol: (ATOM CURRENT)


File: sbcl.info,  Node: Read Errors,  Prev: Errors During Macroexpansion,  Up: Compiler Errors

4.4.3 Read Errors
-----------------

SBCL's compiler does not attempt to recover from read errors when
reading a source file, but instead just reports the offending character
position and gives up on the entire source file.


File: sbcl.info,  Node: Open Coding and Inline Expansion,  Next: Interpreter,  Prev: Compiler Errors,  Up: Compiler

4.5 Open Coding and Inline Expansion
====================================

Since Common Lisp forbids the redefinition of standard functions, the
compiler can have special knowledge of these standard functions
embedded in it. This special knowledge is used in various ways (open
coding, inline expansion, source transformation), but the implications
to the user are basically the same:

   * Attempts to redefine standard functions may be frustrated, since
     the function may never be called. Although it is technically
     illegal to redefine standard functions, users sometimes want to
     implicitly redefine these functions when they are debugging using
     the `trace' macro.  Special-casing of standard functions can be
     inhibited using the `notinline' declaration, but even then some
     phases of analysis such as type inferencing are applied by the
     compiler.

   * The compiler can have multiple alternate implementations of
     standard functions that implement different trade-offs of speed,
     space and safety.  This selection is based on the compiler policy,
     *Note Compiler Policy::.


   When a function call is _open coded_, inline code whose effect is
equivalent to the function call is substituted for that function call.
When a function call is _closed coded_, it is usually left as is,
although it might be turned into a call to a different function with
different arguments. As an example, if `nthcdr' were to be open coded,
then

     (nthcdr 4 foobar)

   might turn into

     (cdr (cdr (cdr (cdr foobar))))

   or even

     (do ((i 0 (1+ i))
       (list foobar (cdr foobar)))
       ((= i 4) list))

   If `nth' is closed coded, then

     (nth x l)

   might stay the same, or turn into something like

     (car (nthcdr x l))

   In general, open coding sacrifices space for speed, but some
functions (such as `car') are so simple that they are always
open-coded. Even when not open-coded, a call to a standard function may
be transformed into a different function call (as in the last example)
or compiled as _static call_. Static function call uses a more
efficient calling convention that forbids redefinition.


File: sbcl.info,  Node: Interpreter,  Prev: Open Coding and Inline Expansion,  Up: Compiler

4.6 Interpreter
===============

By default SBCL implements `eval' by calling the native code compiler.
SBCL also includes an interpreter for use in special cases where using
the compiler is undesirable, for example due to compilation overhead.
Unlike in some other Lisp implementations, in SBCL interpreted code is
not safer or more debuggable than compiled code.

   Switching between the compiler and the interpreter is done using the
special variable `sb-ext:*evaluator-mode*'. As of 0.9.17, valid values
for `sb-ext:*evaluator-mode*' are `:compile' and `:interpret'.


File: sbcl.info,  Node: Debugger,  Next: Efficiency,  Prev: Compiler,  Up: Top

5 Debugger
**********

This chapter documents the debugging facilities of SBCL, including the
debugger, single-stepper and `trace', and the effect of `(optimize
debug)' declarations.

* Menu:

* Debugger Entry::
* Debugger Command Loop::
* Stack Frames::
* Variable Access::
* Source Location Printing::
* Debugger Policy Control::
* Exiting Commands::
* Information Commands::
* Function Tracing::
* Single Stepping::


File: sbcl.info,  Node: Debugger Entry,  Next: Debugger Command Loop,  Up: Debugger

5.1 Debugger Entry
==================

* Menu:

* Debugger Banner::
* Debugger Invocation::


File: sbcl.info,  Node: Debugger Banner,  Next: Debugger Invocation,  Up: Debugger Entry

5.1.1 Debugger Banner
---------------------

When you enter the debugger, it looks something like this:

     debugger invoked on a TYPE-ERROR in thread 11184:
       The value 3 is not of type LIST.

     You can type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.

     restarts (invokable by number or by possibly-abbreviated name):
       0: [ABORT   ] Reduce debugger level (leaving debugger, returning to toplevel).
       1: [TOPLEVEL] Restart at toplevel READ/EVAL/PRINT loop.
     (CAR 1 3)
     0]

   The first group of lines describe what the error was that put us in
the debugger.  In this case `car' was called on `3', causing a
`type-error'.

   This is followed by the "beginner help line", which appears only if
`sb-ext:*debugger-beginner-help*' is true (default).

   Next comes a listing of the active restart names, along with their
descriptions - the ways we can restart execution after this error. In
this case, both options return to top-level. Restarts can be selected
by entering the corresponding number or name.

   The current frame appears right underneath the restarts, immediately
followed by the debugger prompt.


File: sbcl.info,  Node: Debugger Invocation,  Prev: Debugger Banner,  Up: Debugger Entry

5.1.2 Debugger Invocation
-------------------------

The debugger is invoked when:

   * `error' is called, and the condition it signals is not handled.

   * `break' is called, or `signal' is called with a condition that
     matches the current `*break-on-signals*'.

   * the debugger is explicitly entered with the `invoke-debugger'
     function.


   When the debugger is invoked by a condition, ANSI mandates that the
value of `*debugger-hook*', if any, be called with two arguments: the
condition that caused the debugger to be invoked and the previous value
of `*debugger-hook*'. When this happens, `*debugger-hook*' is bound to
NIL to prevent recursive errors.  However, ANSI also mandates that
`*debugger-hook*' not be invoked when the debugger is to be entered by
the `break' function. For users who wish to provide an alternate
debugger interface (and thus catch `break' entries into the debugger),
SBCL provides `sb-ext:*invoke-debugger-hook*', which is invoked during
any entry into the debugger.

 -- Variable: sb-ext:*invoke-debugger-hook*
     This is either `nil' or a designator for a function of two
     arguments,    to be run when the debugger is about to be entered.
     The function is    run with `*invoke-debugger-hook*' bound to
     `nil' to minimize recursive    errors, and receives as arguments
     the condition that triggered    debugger entry and the previous
     value of `*invoke-debugger-hook*'

     This mechanism is an `sbcl' extension similar to the standard
     `*debugger-hook*'.     In contrast to `*debugger-hook*', it is
     observed by `invoke-debugger' even when    called by `break'.


File: sbcl.info,  Node: Debugger Command Loop,  Next: Stack Frames,  Prev: Debugger Entry,  Up: Debugger

5.2 Debugger Command Loop
=========================

The debugger is an interactive read-eval-print loop much like the
normal top level, but some symbols are interpreted as debugger commands
instead of being evaluated. A debugger command starts with the symbol
name of the command, possibly followed by some arguments on the same
line. Some commands prompt for additional input. Debugger commands can
be abbreviated by any unambiguous prefix: `help' can be typed as `h',
`he', etc.

   The package is not significant in debugger commands; any symbol with
the name of a debugger command will work. If you want to show the value
of a variable that happens also to be the name of a debugger command
you can wrap the variable in a `progn' to hide it from the command loop.

   The debugger prompt is "`FRAME]'", where FRAME is the number of the
current frame.  Frames are numbered starting from zero at the top (most
recent call), increasing down to the bottom.  The current frame is the
frame that commands refer to.

   It is possible to override the normal printing behaviour in the
debugger by using the `sb-ext:*debug-print-variable-alist*'.

 -- Variable: sb-ext:*debug-print-variable-alist*
     an association list describing new bindings for special variables
     to be used within the debugger. Eg.

           ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))

     The variables in the `car' positions are bound to the values in
     the `cdr' during the execution of some debug commands. When
     evaluating arbitrary expressions in the debugger, the normal
     values of the printer control variables are in effect.

     Initially empty, `*debug-print-variable-alist*' is typically used
     to provide bindings for printer control variables.


File: sbcl.info,  Node: Stack Frames,  Next: Variable Access,  Prev: Debugger Command Loop,  Up: Debugger

5.3 Stack Frames
================

A "stack frame" is the run-time representation of a call to a function;
the frame stores the state that a function needs to remember what it is
doing.  Frames have:

   * "variables" (*note Variable Access::), which are the values being
     operated on.

   * "arguments" to the call (which are really just particularly
     interesting variables).

   * a current source location (*note Source Location Printing::),
     which is the place in the program where the function was running
     when it stopped to call another function, or because of an
     interrupt or error.


* Menu:

* Stack Motion::
* How Arguments are Printed::
* Function Names::
* Debug Tail Recursion::
* Unknown Locations and Interrupts::


File: sbcl.info,  Node: Stack Motion,  Next: How Arguments are Printed,  Up: Stack Frames

5.3.1 Stack Motion
------------------

These commands move to a new stack frame and print the name of the
function and the values of its arguments in the style of a Lisp
function call:

 -- Debugger Command: up
     Move up to the next higher frame.  More recent function calls are
     considered to be higher on the stack.

 -- Debugger Command: down
     Move down to the next lower frame.

 -- Debugger Command: top
     Move to the highest frame, that is, the frame where the debugger
     was entered.

 -- Debugger Command: bottom
     Move to the lowest frame.

 -- Debugger Command: frame [N]
     Move to the frame with the specified number.  Prompts for the
     number if not supplied.  The frame with number 0 is the frame
     where the debugger was entered.


File: sbcl.info,  Node: How Arguments are Printed,  Next: Function Names,  Prev: Stack Motion,  Up: Stack Frames

5.3.2 How Arguments are Printed
-------------------------------

A frame is printed to look like a function call, but with the actual
argument values in the argument positions.  So the frame for this call
in the source:

     (myfun (+ 3 4) 'a)

   would look like this:

     (MYFUN 7 A)

   All keyword and optional arguments are displayed with their actual
values; if the corresponding argument was not supplied, the value will
be the default.  So this call:

     (subseq "foo" 1)

   would look like this:

     (SUBSEQ "foo" 1 3)

   And this call:

     (string-upcase "test case")

   would look like this:

     (STRING-UPCASE "test case" :START 0 :END NIL)

   The arguments to a function call are displayed by accessing the
argument variables.  Although those variables are initialized to the
actual argument values, they can be set inside the function; in this
case the new value will be displayed.

   `&rest' arguments are handled somewhat differently.  The value of
the rest argument variable is displayed as the spread-out arguments to
the call, so:

     (format t "~A is a ~A." "This" 'test)

   would look like this:

     (FORMAT T "~A is a ~A." "This" 'TEST)

   Rest arguments cause an exception to the normal display of keyword
arguments in functions that have both `&rest' and `&key' arguments.  In
this case, the keyword argument variables are not displayed at all; the
rest arg is displayed instead.  So for these functions, only the
keywords actually supplied will be shown, and the values displayed will
be the argument values, not values of the (possibly modified) variables.

   If the variable for an argument is never referenced by the function,
it will be deleted.  The variable value is then unavailable, so the
debugger prints `#<unused-arg>' instead of the value.  Similarly, if
for any of a number of reasons the value of the variable is unavailable
or not known to be available (*note Variable Access::), then
`#<unavailable-arg>' will be printed instead of the argument value.

   Note that inline expansion and open-coding affect what frames are
present in the debugger, see *Note Debugger Policy Control::.


File: sbcl.info,  Node: Function Names,  Next: Debug Tail Recursion,  Prev: How Arguments are Printed,  Up: Stack Frames

5.3.3 Function Names
--------------------

If a function is defined by `defun' it will appear in backtrace by that
name. Functions defined by `labels' and `flet' will appear as `(FLET
<name>)' and `(LABELS <name>)' respectively.  Anonymous lambdas will
appear as `(LAMDBA <lambda-list>)'.

* Menu:

* Entry Point Details::


File: sbcl.info,  Node: Entry Point Details,  Up: Function Names

5.3.3.1 Entry Point Details
...........................

Sometimes the compiler introduces new functions that are used to
implement a user function, but are not directly specified in the
source. This is mostly done for argument type and count checking.

   The debugger will normally show these entry point functions as if
they were the normal main entry point, but more detail can be obtained
by setting `sb-debug:*show-entry-point-details*' to true; this is
primarily useful for debugging SBCL itself, but may help pinpoint
problems that occur during lambda-list processing.

   With recursive functions, an additional `:EXTERNAL' frame may appear
before the frame representing the first call to the recursive function.
This is a consequence of the way the compiler works: there is nothing
odd with your program. You will also see `:CLEANUP' frames during the
execution of `unwind-protect' cleanup code.  The `:EXTERNAL' and
`:CLEANUP' above are entry-point types, visible only if
`sb-debug:*show-entry-point-details*' os true.


File: sbcl.info,  Node: Debug Tail Recursion,  Next: Unknown Locations and Interrupts,  Prev: Function Names,  Up: Stack Frames

5.3.4 Debug Tail Recursion
--------------------------

The compiler is "properly tail recursive." If a function call is in a
tail-recursive position, the stack frame will be deallocated _at the
time of the call_, rather than after the call returns.  Consider this
backtrace:

     (BAR ...)
     (FOO ...)

   Because of tail recursion, it is not necessarily the case that `FOO'
directly called `BAR'.  It may be that `FOO' called some other function
`FOO2' which then called `BAR' tail-recursively, as in this example:

     (defun foo ()
       ...
       (foo2 ...)
       ...)

     (defun foo2 (...)
       ...
       (bar ...))

     (defun bar (...)
       ...)

   Usually the elimination of tail-recursive frames makes debugging more
pleasant, since these frames are mostly uninformative.  If there is any
doubt about how one function called another, it can usually be
eliminated by finding the source location in the calling frame.  *Note
Source Location Printing::.

   The elimination of tail-recursive frames can be prevented by
disabling tail-recursion optimization, which happens when the `debug'
optimization quality is greater than `2'.  *Note Debugger Policy
Control::.


File: sbcl.info,  Node: Unknown Locations and Interrupts,  Prev: Debug Tail Recursion,  Up: Stack Frames

5.3.5 Unknown Locations and Interrupts
--------------------------------------

The debugger operates using special debugging information attached to
the compiled code.  This debug information tells the debugger what it
needs to know about the locations in the code where the debugger can be
invoked.  If the debugger somehow encounters a location not described
in the debug information, then it is said to be "unknown".  If the code
location for a frame is unknown, then some variables may be
inaccessible, and the source location cannot be precisely displayed.

   There are three reasons why a code location could be unknown:

   * There is inadequate debug information due to the value of the
     `debug' optimization quality.  *Note Debugger Policy Control::.

   * The debugger was entered because of an interrupt such as <C-c>.

   * A hardware error such as "`bus error'" occurred in code that was
     compiled unsafely due to the value of the `safety' optimization
     quality.


   In the last two cases, the values of argument variables are
accessible, but may be incorrect.  For more details on when variable
values are accessible, *Note Variable Value Availability::.

   It is possible for an interrupt to happen when a function call or
return is in progress.  The debugger may then flame out with some
obscure error or insist that the bottom of the stack has been reached,
when the real problem is that the current stack frame can't be located.
If this happens, return from the interrupt and try again.


File: sbcl.info,  Node: Variable Access,  Next: Source Location Printing,  Prev: Stack Frames,  Up: Debugger

5.4 Variable Access
===================

There are two ways to access the current frame's local variables in the
debugger: `list-locals' and `sb-debug:var'.

   The debugger doesn't really understand lexical scoping; it has just
one namespace for all the variables in the current stack frame.  If a
symbol is the name of multiple variables in the same function, then the
reference appears ambiguous, even though lexical scoping specifies
which value is visible at any given source location.  If the scopes of
the two variables are not nested, then the debugger can resolve the
ambiguity by observing that only one variable is accessible.

   When there are ambiguous variables, the evaluator assigns each one a
small integer identifier.  The `sb-debug:var' function uses this
identifier to distinguish between ambiguous variables.  The
`list-locals' command prints the identifier.  In the following example,
there are two variables named `X'.  The first one has identifier 0
(which is not printed), the second one has identifier 1.

     X  =  1
     X#1  =  2

 -- Debugger Command: list-locals [PREFIX]
     This command prints the name and value of all variables in the
     current frame whose name has the specified PREFIX.  PREFIX may be
     a string or a symbol.  If no PREFIX is given, then all available
     variables are printed.  If a variable has a potentially ambiguous
     name, then the name is printed with a "`#IDENTIFIER'" suffix,
     where IDENTIFIER is the small integer used to make the name unique.

 -- Function: sb-debug:var NAME &optional IDENTIFIER
     This function returns the value of the variable in the current
     frame with the specified NAME.  If supplied, IDENTIFIER determines
     which value to return when there are ambiguous variables.

     When NAME is a symbol, it is interpreted as the symbol name of the
     variable, i.e. the package is significant.  If NAME is an
     uninterned symbol (gensym), then return the value of the uninterned
     variable with the same name.  If NAME is a string, `sb-debug:var'
     interprets it as the prefix of a variable name that must
     unambiguously complete to the name of a valid variable.

     IDENTIFIER is used to disambiguate the variable name; use
     `list-locals' to find out the identifiers.

* Menu:

* Variable Value Availability::
* Note On Lexical Variable Access::


File: sbcl.info,  Node: Variable Value Availability,  Next: Note On Lexical Variable Access,  Up: Variable Access

5.4.1 Variable Value Availability
---------------------------------

The value of a variable may be unavailable to the debugger in portions
of the program where Lisp says that the variable is defined.  If a
variable value is not available, the debugger will not let you read or
write that variable.  With one exception, the debugger will never
display an incorrect value for a variable.  Rather than displaying
incorrect values, the debugger tells you the value is unavailable.

   The one exception is this: if you interrupt (e.g., with <C-c>) or if
there is an unexpected hardware error such as "`bus error'" (which
should only happen in unsafe code), then the values displayed for
arguments to the interrupted frame might be incorrect.(1)  This
exception applies only to the interrupted frame: any frame farther down
the stack will be fine.

   The value of a variable may be unavailable for these reasons:

   * The value of the `debug' optimization quality may have omitted
     debug information needed to determine whether the variable is
     available.  Unless a variable is an argument, its value will only
     be available when `debug' is at least `2'.

   * The compiler did lifetime analysis and determined that the value
     was no longer needed, even though its scope had not been exited.
     Lifetime analysis is inhibited when the `debug' optimization
     quality is `3'.

   * The variable's name is an uninterned symbol (gensym).  To save
     space, the compiler only dumps debug information about uninterned
     variables when the `debug' optimization quality is `3'.

   * The frame's location is unknown (*note Unknown Locations and
     Interrupts::) because the debugger was entered due to an interrupt
     or unexpected hardware error.  Under these conditions the values of
     arguments will be available, but might be incorrect.  This is the
     exception mentioned above.

   * The variable (or the code referencing it) was optimized out of
     existence.  Variables with no reads are always optimized away.  The
     degree to which the compiler deletes variables will depend on the
     value of the `compilation-speed' optimization quality, but most
     source-level optimizations are done under all compilation policies.

   * The variable is never set and its definition looks like
          (LET ((var1 var2))
             ...)
     In this case, `var1' is substituted with `var2'.

   * The variable is never set and is referenced exactly once.  In this
     case, the reference is substituted with the variable initial value.


   Since it is especially useful to be able to get the arguments to a
function, argument variables are treated specially when the `speed'
optimization quality is less than `3' and the `debug' quality is at
least `1'.  With this compilation policy, the values of argument
variables are almost always available everywhere in the function, even
at unknown locations.  For non-argument variables, `debug' must be at
least `2' for values to be available, and even then, values are only
available at known locations.

   ---------- Footnotes ----------

   (1) Since the location of an interrupt or hardware error will always
be an unknown location, non-argument variable values will never be
available in the interrupted frame.  *Note Unknown Locations and
Interrupts::.


File: sbcl.info,  Node: Note On Lexical Variable Access,  Prev: Variable Value Availability,  Up: Variable Access

5.4.2 Note On Lexical Variable Access
-------------------------------------

When the debugger command loop establishes variable bindings for
available variables, these variable bindings have lexical scope and
dynamic extent.(1)  You can close over them, but such closures can't be
used as upward funargs.

   You can also set local variables using `setq', but if the variable
was closed over in the original source and never set, then setting the
variable in the debugger may not change the value in all the functions
the variable is defined in.  Another risk of setting variables is that
you may assign a value of a type that the compiler proved the variable
could never take on.  This may result in bad things happening.

   ---------- Footnotes ----------

   (1) The variable bindings are actually created using the Lisp
`symbol-macrolet' special form.


File: sbcl.info,  Node: Source Location Printing,  Next: Debugger Policy Control,  Prev: Variable Access,  Up: Debugger

5.5 Source Location Printing
============================

One of the debugger's capabilities is source level debugging of
compiled code.  These commands display the source location for the
current frame:

 -- Debugger Command: source [CONTEXT]
     This command displays the file that the current frame's function
     was defined from (if it was defined from a file), and then the
     source form responsible for generating the code that the current
     frame was executing.  If CONTEXT is specified, then it is an
     integer specifying the number of enclosing levels of list
     structure to print.

   The source form for a location in the code is the innermost list
present in the original source that encloses the form responsible for
generating that code.  If the actual source form is not a list, then
some enclosing list will be printed.  For example, if the source form
was a reference to the variable `*some-random-special*', then the
innermost enclosing evaluated form will be printed.  Here are some
possible enclosing forms:

     (let ((a *some-random-special*))
       ...)

     (+ *some-random-special* ...)

   If the code at a location was generated from the expansion of a macro
or a source-level compiler optimization, then the form in the original
source that expanded into that code will be printed.  Suppose the file
`/usr/me/mystuff.lisp' looked like this:

     (defmacro mymac ()
       '(myfun))

     (defun foo ()
       (mymac)
       ...)

   If `foo' has called `myfun', and is waiting for it to return, then
the `source' command would print:

     ; File: /usr/me/mystuff.lisp

     (MYMAC)

   Note that the macro use was printed, not the actual function call
form, `(myfun)'.

   If enclosing source is printed by giving an argument to `source' or
`vsource', then the actual source form is marked by wrapping it in a
list whose first element is `#:***HERE***'.  In the previous example,
`source 1' would print:

     ; File: /usr/me/mystuff.lisp

     (DEFUN FOO ()
       (#:***HERE***
        (MYMAC))
       ...)

* Menu:

* How the Source is Found::
* Source Location Availability::


File: sbcl.info,  Node: How the Source is Found,  Next: Source Location Availability,  Up: Source Location Printing

5.5.1 How the Source is Found
-----------------------------

If the code was defined from Lisp by `compile' or `eval', then the
source can always be reliably located.  If the code was defined from a
`fasl' file created by `compile-file', then the debugger gets the
source forms it prints by reading them from the original source file.
This is a potential problem, since the source file might have moved or
changed since the time it was compiled.

   The source file is opened using the `truename' of the source file
pathname originally given to the compiler.  This is an absolute pathname
with all logical names and symbolic links expanded.  If the file can't
be located using this name, then the debugger gives up and signals an
error.

   If the source file can be found, but has been modified since the
time it was compiled, the debugger prints this warning:

     ; File has been modified since compilation:
     ;   FILENAME
     ; Using form offset instead of character position.

   where FILENAME is the name of the source file.  It then proceeds
using a robust but not foolproof heuristic for locating the source.
This heuristic works if:

   * No top-level forms before the top-level form containing the source
     have been added or deleted, and

   * The top-level form containing the source has not been modified
     much.  (More precisely, none of the list forms beginning before
     the source form have been added or deleted.)


   If the heuristic doesn't work, the displayed source will be wrong,
but will probably be near the actual source.  If the "shape" of the
top-level form in the source file is too different from the original
form, then an error will be signaled.  When the heuristic is used, the
source location commands are noticeably slowed.

   Source location printing can also be confused if (after the source
was compiled) a read-macro you used in the code was redefined to expand
into something different, or if a read-macro ever returns the same `eq'
list twice.  If you don't define read macros and don't use `##' in
perverted ways, you don't need to worry about this.


File: sbcl.info,  Node: Source Location Availability,  Prev: How the Source is Found,  Up: Source Location Printing

5.5.2 Source Location Availability
----------------------------------

Source location information is only available when the `debug'
optimization quality is at least `2'.  If source location information
is unavailable, the source commands will give an error message.

   If source location information is available, but the source location
is unknown because of an interrupt or unexpected hardware error (*note
Unknown Locations and Interrupts::), then the command will print:

     Unknown location: using block start.

   and then proceed to print the source location for the start of the
_basic block_ enclosing the code location.  It's a bit complicated to
explain exactly what a basic block is, but here are some properties of
the block start location:

   * The block start location may be the same as the true location.

   * The block start location will never be later in the program's flow
     of control than the true location.

   * No conditional control structures (such as `if', `cond', `or')
     will intervene between the block start and the true location (but
     note that some conditionals present in the original source could
     be optimized away.)  Function calls _do not_ end basic blocks.

   * The head of a loop will be the start of a block.

   * The programming language concept of "block structure" and the Lisp
     `block' special form are totally unrelated to the compiler's basic
     block.


   In other words, the true location lies between the printed location
and the next conditional (but watch out because the compiler may have
changed the program on you.)


File: sbcl.info,  Node: Debugger Policy Control,  Next: Exiting Commands,  Prev: Source Location Printing,  Up: Debugger

5.6 Debugger Policy Control
===========================

The compilation policy specified by `optimize' declarations affects the
behavior seen in the debugger.  The `debug' quality directly affects
the debugger by controlling the amount of debugger information dumped.
Other optimization qualities have indirect but observable effects due
to changes in the way compilation is done.

   Unlike the other optimization qualities (which are compared in
relative value to evaluate tradeoffs), the `debug' optimization quality
is directly translated to a level of debug information.  This absolute
interpretation allows the user to count on a particular amount of debug
information being available even when the values of the other qualities
are changed during compilation.  These are the levels of debug
information that correspond to the values of the `debug' quality:

`0'
     Only the function name and enough information to allow the stack to
     be parsed.

`> 0'
     Any level greater than `0' gives level `0' plus all argument
     variables.  Values will only be accessible if the argument
     variable is never set and `speed' is not `3'.  SBCL allows any real
     value for optimization qualities.  It may be useful to specify
     `0.5' to get backtrace argument display without argument
     documentation.

`1'
     Level `1' provides argument documentation (printed arglists) and
     derived argument/result type information.  This makes `describe'
     more informative, and allows the compiler to do compile-time
     argument count and type checking for any calls compiled at
     run-time.  This is the default.

`2'
     Level `1' plus all interned local variables, source location
     information, and lifetime information that tells the debugger when
     arguments are available (even when `speed' is `3' or the argument
     is set).

`> 2'
     Any level greater than `2' gives level `2' and in addition
     disables tail-call optimization, so that the backtrace will contain
     frames for all invoked functions, even those in tail positions.

`3'
     Level `2' plus all uninterned variables.  In addition, lifetime
     analysis is disabled (even when `speed' is `3'), ensuring that all
     variable values are available at any known location within the
     scope of the binding.  This has a speed penalty in addition to the
     obvious space penalty.

`> (max speed space)'
     If `debug' is greater than both `speed' and `space', the command
     `return' can be used to continue execution by returning a value
     from the current stack frame.

`> (max speed space compilation-speed)'
     If `debug' is greater than all of `speed', `space' and
     `compilation-speed' the code will be steppable (*note Single
     Stepping::).


   As you can see, if the `speed' quality is `3', debugger performance
is degraded.  This effect comes from the elimination of argument
variable special-casing (*note Variable Value Availability::).  Some
degree of speed/debuggability tradeoff is unavoidable, but the effect
is not too drastic when `debug' is at least `2'.

   In addition to `inline' and `notinline' declarations, the relative
values of the `speed' and `space' qualities also change whether
functions are inline expanded.  If a function is inline expanded, then
there will be no frame to represent the call, and the arguments will be
treated like any other local variable.  Functions may also be
"semi-inline", in which case there is a frame to represent the call,
but the call is to an optimized local version of the function, not to
the original function.


File: sbcl.info,  Node: Exiting Commands,  Next: Information Commands,  Prev: Debugger Policy Control,  Up: Debugger

5.7 Exiting Commands
====================

These commands get you out of the debugger.

 -- Debugger Command: toplevel
     Throw to top level.

 -- Debugger Command: restart [N]
     Invokes the Nth restart case as displayed by the `error' command.
     If N is not specified, the available restart cases are reported.

 -- Debugger Command: continue
     Calls `continue' on the condition given to `debug'.  If there is no
     restart case named CONTINUE, then an error is signaled.

 -- Debugger Command: abort
     Calls `abort' on the condition given to `debug'.  This is useful
     for popping debug command loop levels or aborting to top level, as
     the case may be.

 -- Debugger Command: return VALUE
     Returns VALUE from the current stack frame.  This command is
     available when the `debug' optimization quality is greater than
     both `speed' and `space'.  Care must be taken that the value is of
     the same type as SBCL expects the stack frame to return.

 -- Debugger Command: restart-frame
     Restarts execution of the current stack frame. This command is
     available when the `debug' optimization quality is greater than
     both `speed' and `space' and when the frame is for is a global
     function. If the function is redefined in the debugger before the
     frame is restarted, the new function will be used.


File: sbcl.info,  Node: Information Commands,  Next: Function Tracing,  Prev: Exiting Commands,  Up: Debugger

5.8 Information Commands
========================

Most of these commands print information about the current frame or
function, but a few show general information.

 -- Debugger Command: help
 -- Debugger Command: ?
     Displays a synopsis of debugger commands.

 -- Debugger Command: describe
     Calls `describe' on the current function and displays the number of
     local variables.

 -- Debugger Command: print
     Displays the current function call as it would be displayed by
     moving to this frame.

 -- Debugger Command: error
     Prints the condition given to `invoke-debugger' and the active
     proceed cases.

 -- Debugger Command: backtrace [N]
     Displays all the frames from the current to the bottom. Only shows
     N frames if specified. The printing is controlled by
     `*debug-print-variable-alist*'.


File: sbcl.info,  Node: Function Tracing,  Next: Single Stepping,  Prev: Information Commands,  Up: Debugger

5.9 Function Tracing
====================

The tracer causes selected functions to print their arguments and their
results whenever they are called.  Options allow conditional printing
of the trace information and conditional breakpoints on function entry
or exit.

 -- Macro: cl:trace &rest specs
     `trace' {Option Global-Value}* {Name {Option Value}*}*

     `trace' is a debugging tool that provides information when
     specified functions are called. In its simplest form:

                 (TRACE NAME-1 NAME-2 ...)

     The NAMEs are not evaluated. Each may be a symbol, denoting an
     individual function, or a string, denoting all functions fbound to
     symbols whose home package is the package with the given name.

     Options allow modification of the default behavior. Each option is
     a pair of an option keyword and a value form. Global options are
     specified before the first name, and affect all functions traced
     by a given use of `trace'. Options may also be interspersed with
     function names, in which case they act as local options, only
     affecting tracing of the immediately preceding function name.
     Local options override global options.

     By default, `trace' causes a printout on `*trace-output*' each
     time that one of the named functions is entered or returns. (This
     is the basic, `ansi' Common Lisp behavior of `trace'.) As an
     `sbcl' extension, the `:report' `sb-ext:profile' option can be
     used to instead cause information to be silently recorded to be
     inspected later using the `sb-ext:profile' function.

     The following options are defined:

    _`:report' Report-Type_
          If Report-Type is `trace' (the default) then information is
          reported        by printing immediately. If Report-Type is
          `sb-ext:profile', information        is recorded for later
          summary by calls to `sb-ext:profile'. If        Report-Type
          is `nil', then the only effect of the trace is to execute
            other options (e.g. `print' or BREAK).

    _`:condition' Form_
    _`:condition-after' Form_
    _`:condition-all' Form_
          If `:condition' is specified, then `trace' does nothing
          unless Form        evaluates to true at the time of the call.
          `:condition-after' is        similar, but suppresses the
          initial printout, and is tested when the        function
          returns. `:condition-all' tries both before and after.
          This option is not supported with `:report' `profile'.

    _`:break' Form_
    _`:break-after' Form_
    _`:break-all' Form_
          If specified, and Form evaluates to true, then the debugger
          is invoked        at the start of the function, at the end of
          the function, or both,        according to the respective
          option.

    _`:print' Form_
    _`:print-after' Form_
    _`:print-all' Form_
          In addition to the usual printout, the result of evaluating
          Form is        printed at the start of the function, at the
          end of the function, or        both, according to the
          respective option. Multiple print options cause
          multiple values to be printed.

    _`:wherein' Names_
          If specified, Names is a function name or list of names.
          `trace' does        nothing unless a call to one of those
          functions encloses the call to        this function (i.e. it
          would appear in a backtrace.)  Anonymous        functions
          have string names like "DEFUN FOO". This option is not
          supported with `:report' `profile'.

    _`:encapsulate' {:DEFAULT | `t' | NIL}_
          If `t', the tracing is done via encapsulation (redefining the
          function        name) rather than by modifying the function.
          `:default' is the default,        and means to use
          encapsulation for interpreted functions and funcallable
          instances, breakpoints otherwise. When encapsulation is
          used, forms are        *not* evaluated in the function's
          lexical environment, but `sb-debug:arg'        can still be
          used.

    _`:methods' {T | NIL}_
          If `t', any function argument naming a generic function will
          have its        methods traced in addition to the generic
          function itself.

    _`:function' Function-Form_
          This is a not really an option, but rather another way of
          specifying        what function to trace. The Function-Form
          is evaluated immediately,        and the resulting function
          is instrumented, i.e. traced or profiled        as specified
          in `report'.


     `:condition', `:break' and `:print' forms are evaluated in a
     context which mocks up the lexical environment of the called
     function, so that `sb-debug:var' and `sb-debug:arg' can be used.
     The `-after' and `-all' forms are evaluated in the null
     environment.

 -- Macro: cl:untrace &rest specs
     Remove tracing from the specified functions. Untraces all
     functions when called with no arguments.

 -- Variable: sb-debug:*trace-indentation-step*
     the increase in trace indentation at each call level

 -- Variable: sb-debug:*max-trace-indentation*
     If the trace indentation exceeds this value, then indentation
     restarts at    0.

 -- Variable: sb-debug:*trace-encapsulate-default*
     the default value for the `:encapsulate' option to `trace'

 -- Variable: sb-debug:*trace-values*
     This is bound to the returned values when evaluating
     `:break-after' and    `:print-after' forms.


File: sbcl.info,  Node: Single Stepping,  Prev: Function Tracing,  Up: Debugger

5.10 Single Stepping
====================

SBCL includes an instrumentation based single-stepper for compiled
code, that can be invoked via the `step' macro, or from within the
debugger. *Note Debugger Policy Control::, for details on enabling
stepping for compiled code.

   The following debugger commands are used for controlling single
stepping.

 -- Debugger Command: start
     Selects the `continue' restart if one exists and starts single
     stepping.  None of the other single stepping commands can be used
     before stepping has been started either by using `start' or by
     using the standard `step' macro.

 -- Debugger Command: step
     Steps into the current form. Stepping will be resumed when the next
     form that has been compiled with stepper instrumentation is
     evaluated.

 -- Debugger Command: next
     Steps over the current form. Stepping will be disabled until
     evaluation of the form is complete.

 -- Debugger Command: out
     Steps out of the current frame. Stepping will be disabled until the
     topmost stack frame that had been stepped into returns.

 -- Debugger Command: stop
     Stops the single stepper and resumes normal execution.

 -- Macro: cl:step form
     The form is evaluated with single stepping enabled. Function calls
     outside the lexical scope of the form can be stepped into only if
     the functions in question have been compiled with sufficient
     `debug' policy to be at least partially steppable.


File: sbcl.info,  Node: Efficiency,  Next: Beyond the ANSI Standard,  Prev: Debugger,  Up: Top

6 Efficiency
************

* Menu:

* Slot access::
* Dynamic-extent allocation::
* Modular arithmetic::
* Global and Always-Bound variables::
* Miscellaneous Efficiency Issues::


File: sbcl.info,  Node: Slot access,  Next: Dynamic-extent allocation,  Up: Efficiency

6.1 Slot access
===============

6.1.1 Structure object slot access
----------------------------------

Structure slot accessors are efficient only if the compiler is able to
open code them: compiling a call to a structure slot accessor before
the structure is defined, declaring one `notinline', or passing it as a
functional argument to another function causes severe perfomance
degradation.

6.1.2 Standard object slot access
---------------------------------

The most efficient way to access a slot of a `standard-object' is by
using `slot-value' with a constant slot name argument inside a
`defmethod' body, where the variable holding the instance is a
specializer parameter of the method and is never assigned to. The cost
is roughly 1.6 times that of an open coded structure slot accessor.

   Second most efficient way is to use a CLOS slot accessor, or
`slot-value' with a constant slot name argument, but in circumstances
other than specified above. This may be up to 3 times as slow as the
method described above.

   Example:

     (defclass foo () ((bar)))

     ;; Fast: specializer and never assigned to
     (defmethod quux ((foo foo) new)
       (let ((old (slot-value foo 'bar)))
         (setf (slot-value foo 'bar) new)
         old))

     ;; Slow: not a specializer
     (defmethod quux ((foo foo) new)
       (let* ((temp foo)
              (old (slot-value temp 'bar)))
         (setf (slot-value temp 'bar) new)
         old))

     ;; Slow: assignment to FOO
     (defmethod quux ((foo foo) new)
       (let ((old (slot-value foo 'bar)))
         (setf (slot-value foo 'bar) new)
         (setf foo new)
         old))

   Note that when profiling code such as this, the first few calls to
the generic function are not representative, as the dispatch mechanism
is lazily set up during those calls.


File: sbcl.info,  Node: Dynamic-extent allocation,  Next: Modular arithmetic,  Prev: Slot access,  Up: Efficiency

6.2 Dynamic-extent allocation
=============================

SBCL has limited support for performing allocation on the stack when a
variable is declared `dynamic-extent'. The `dynamic-extent'
declarations are not verified, but are simply trusted as long as
`sb-ext:*stack-allocate-dynamic-extent*' is true.

   If dynamic extent constraints specified in the Common Lisp standard
are violated, the best that can happen is for the program to have
garbage in variables and return values; more commonly, the system will
crash.

 -- Variable: sb-ext:*stack-allocate-dynamic-extent*
     If true (the default), the compiler respects `dynamic-extent'
     declarations and stack allocates otherwise inaccessible parts of
     the object whenever possible. Potentially long (over one page in
     size) vectors are, however, not stack allocated except in zero
     `safety' code, as such a vector could overflow the stack without
     triggering overflow protection.

   There are many cases when `dynamic-extent' declarations could be
useful. At present, SBCL implements stack allocation for

   * `&rest' lists, when these are declared `dynamic-extent'.

   * `cons', `list', `list*', and `vector' when the result is bound to
     a variable declared `dynamic-extent'.

   * simple forms of `make-array', whose result is bound to a variable
     declared `dynamic-extent': stack allocation is possible only if
     the resulting array is known to be both simple and one-dimensional,
     and has a constant `:element-type'.

     *Note*: stack space is limited, so allocation of a large vector
     may cause stack overflow. For this reason potentially large
     vectors, which might circumvent stack overflow detection, are
     stack allocated only in zero `safety' policies.

   * closures defined with `flet' or `labels', with a bound
     `dynamic-extent' declaration. Closed-over variables, which are
     assigned to (either inside or outside the closure) are still
     allocated on the heap. Blocks and tags are also allocated on the
     heap, unless all non-local control transfers to them are compiled
     with zero `safety'.

   * user-defined structures when the structure constructor defined
     using `defstruct' has been declared `inline' and the result of the
     call to the constructor is bound to a variable declared
     `dynamic-extent'.

     *Note_* structures with "raw" slots can currently be
     stack-allocated only on x86 and x86-64.

   * all of the above when they appear as initial parts of another
     stack-allocated object.


   Examples:

     ;;; Declaiming a structure constructor inline before definition makes
     ;;; stack allocation possible.
     (declaim (inline make-thing))
     (defstruct thing obj next)

     ;;; Stack allocation of various objects bound to DYNAMIC-EXTENT
     ;;; variables.
     (let* ((list (list 1 2 3))
            (nested (cons (list 1 2) (list* 3 4 (list 5))))
            (vector (make-array 3 :element-type 'single-float))
            (thing (make-thing :obj list
                               :next (make-thing :obj (make-array 3)))))
       (declare (dynamic-extent list nested vector thing))
       ...)

     ;;; Stack allocation of arguments to a local function is equivalent
     ;;; to stack allocation of local variable values.
     (flet ((f (x)
              (declare (dynamic-extent x))
              ...))
       ...
       (f (list 1 2 3))
       (f (cons (cons 1 2) (cons 3 4)))
       ...)

     ;;; Stack allocation of &REST lists
     (defun foo (&rest args)
       (declare (dynamic-extent args))
       ...)

   Future plans include

   * Stack allocation of assigned-to closed-over variables, where these
     are declared `dynamic-extent';

   * Automatic detection of the common idiom of applying a function to
     some defaults and a `&rest' list, even when this is not declared
     `dynamic-extent';

   * Automatic detection of the common idiom of calling quantifiers
     with a closure, even when the closure is not declared
     `dynamic-extent'.



File: sbcl.info,  Node: Modular arithmetic,  Next: Global and Always-Bound variables,  Prev: Dynamic-extent allocation,  Up: Efficiency

6.3 Modular arithmetic
======================

Some numeric functions have a property: N lower bits of the result
depend only on N lower bits of (all or some) arguments. If the compiler
sees an expression of form `(logand EXP MASK)', where EXP is a tree of
such "good" functions and MASK is known to be of type `(unsigned-byte
W)', where W is a "good" width, all intermediate results will be cut to
W bits (but it is not done for variables and constants!). This often
results in an ability to use simple machine instructions for the
functions.

   Consider an example.

     (defun i (x y)
       (declare (type (unsigned-byte 32) x y))
       (ldb (byte 32 0) (logxor x (lognot y))))

   The result of `(lognot y)' will be negative and of type
`(signed-byte 33)', so a naive implementation on a 32-bit platform is
unable to use 32-bit arithmetic here. But modular arithmetic optimizer
is able to do it: because the result is cut down to 32 bits, the
compiler will replace `logxor' and `lognot' with versions cutting
results to 32 bits, and because terminals (here--expressions `x' and
`y') are also of type `(unsigned-byte 32)', 32-bit machine arithmetic
can be used.

   As of SBCL 0.8.5 "good" functions are `+', `-'; `logand', `logior',
`logxor', `lognot' and their combinations; and `ash' with the positive
second argument. "Good" widths are 32 on HPPA, MIPS, PPC, Sparc and x86
and 64 on Alpha.  While it is possible to support smaller widths as
well, currently this is not implemented.


File: sbcl.info,  Node: Global and Always-Bound variables,  Next: Miscellaneous Efficiency Issues,  Prev: Modular arithmetic,  Up: Efficiency

6.4 Global and Always-Bound variables
=====================================

 -- Macro: sb-ext:defglobal name value &optional doc
     Defines `name' as a global variable that is always bound. `value'
     is evaluated and assigned to `name' both at compile- and
     load-time, but only if `name' is not already bound.

     Global variables share their values between all threads, and
     cannot be locally bound, declared special, defined as constants,
     and neither bound nor defined as symbol macros.

     See also the declarations `sb-ext:global' and
     `sb-ext:always-bound'.

 -- Declaration: sb-ext:global
     Syntax: `(sb-ext:global symbol*)'

     Only valid as a global proclamation.

     Specifies that the named symbols cannot be proclaimed or locally
     declared `special'. Proclaiming an already special or constant
     variable name as `global' signal an error. Allows more efficient
     value lookup in threaded environments in addition to expressing
     programmer intention.

 -- Declaration: sb-ext:always-bound
     Syntax: `(sb-ext:always-bound symbol*)'

     Only valid as a global proclamation.

     Specifies that the named symbols is always bound. Inhibits
     `makunbound' of the named symbols. Proclaiming an unbound symbol
     as `always-bound' signals an error. Allows compiler to elide
     boundness checks from value lookups.


File: sbcl.info,  Node: Miscellaneous Efficiency Issues,  Prev: Global and Always-Bound variables,  Up: Efficiency

6.5 Miscellaneous Efficiency Issues
===================================

FIXME: The material in the CMUCL manual about getting good performance
from the compiler should be reviewed, reformatted in Texinfo, lightly
edited for SBCL, and substituted into this manual. In the meantime, the
original CMUCL manual is still 95+% correct for the SBCL version of the
Python compiler. See the sections

   * Advanced Compiler Use and Efficiency Hints

   * Advanced Compiler Introduction

   * More About Types in Python

   * Type Inference

   * Source Optimization

   * Tail Recursion

   * Local Call

   * Block Compilation

   * Inline Expansion

   * Object Representation

   * Numbers

   * General Efficiency Hints

   * Efficiency Notes

   Besides this information from the CMUCL manual, there are a few other
points to keep in mind.

   * The CMUCL manual doesn't seem to state it explicitly, but Python
     has a mental block about type inference when assignment is
     involved. Python is very aggressive and clever about inferring the
     types of values bound with `let', `let*', inline function call,
     and so forth. However, it's much more passive and dumb about
     inferring the types of values assigned with `setq', `setf', and
     friends. It would be nice to fix this, but in the meantime don't
     expect that just because it's very smart about types in most
     respects it will be smart about types involved in assignments.
     (This doesn't affect its ability to benefit from explicit type
     declarations involving the assigned variables, only its ability to
     get by without explicit type declarations.)

   * Since the time the CMUCL manual was written, CMUCL (and thus SBCL)
     has gotten a generational garbage collector. This means that there
     are some efficiency implications of various patterns of memory
     usage which aren't discussed in the CMUCL manual. (Some new
     material should be written about this.)

   * SBCL has some important known efficiency problems.  Perhaps the
     most important are

        - The garbage collector is not particularly efficient, at least
          on platforms without the generational collector (as of SBCL
          0.8.9, all except x86).

        - Various aspects of the PCL implementation of CLOS are more
          inefficient than necessary.



   Finally, note that Common Lisp defines many constructs which, in the
infamous phrase, "could be compiled efficiently by a sufficiently smart
compiler". The phrase is infamous because making a compiler which
actually is sufficiently smart to find all these optimizations
systematically is well beyond the state of the art of current compiler
technology. Instead, they're optimized on a case-by-case basis by
hand-written code, or not optimized at all if the appropriate case
hasn't been hand-coded. Some cases where no such hand-coding has been
done as of SBCL version 0.6.3 include

   * `(reduce #'f x)' where the type of `x' is known at compile time

   * various bit vector operations, e.g.  `(position 0 some-bit-vector)'

   * specialized sequence idioms, e.g.  `(remove item list :count 1)'

   * cases where local compilation policy does not require excessive
     type checking, e.g.  `(locally (declare (safety 1)) (assoc item
     list))' (which currently performs safe `endp' checking internal to
     assoc).


   If your system's performance is suffering because of some construct
which could in principle be compiled efficiently, but which the SBCL
compiler can't in practice compile efficiently, consider writing a
patch to the compiler and submitting it for inclusion in the main
sources. Such code is often reasonably straightforward to write; search
the sources for the string "`deftransform'" to find many examples (some
straightforward, some less so).


File: sbcl.info,  Node: Beyond the ANSI Standard,  Next: Foreign Function Interface,  Prev: Efficiency,  Up: Top

7 Beyond the ANSI Standard
**************************

SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn't support as many extensions as CMUCL, but it
still has quite a few.  *Note Contributed Modules::.

* Menu:

* Garbage Collection::
* Metaobject Protocol::
* Support For Unix::
* Customization Hooks for Users::
* Tools To Help Developers::
* Resolution of Name Conflicts::
* Hash Table Extensions::
* Miscellaneous Extensions::
* Stale Extensions::
* Efficiency Hacks::


File: sbcl.info,  Node: Garbage Collection,  Next: Metaobject Protocol,  Up: Beyond the ANSI Standard

7.1 Garbage Collection
======================

SBCL provides additional garbage collection functionality not specified
by ANSI. Weak pointers allow references to objects to be maintained
without keeping them from being garbage collected, and "finalization"
hooks are available to cause code to be executed when an object has
been garbage collected. Additionally users can specify their own
cleanup actions to be executed with garbage collection. See also
`make-hash-table' for information on weak hash tables.

 -- Function: sb-ext:finalize object function &key dont-save
     Arrange for the designated `function' to be called when there are
     no more references to `object', including references in `function'
     itself.

     If `dont-save' is true, the finalizer will be cancelled when
     `save-lisp-and-die' is called: this is useful for finalizers
     deallocating system memory, which might otherwise be called with
     addresses from the old image.

     In a multithreaded environment `function' may be called in any
     thread. In both single and multithreaded environments `function'
     may be called in any dynamic scope: consequences are unspecified
     if `function' is not fully re-entrant.

     Errors from `function' are handled and cause a `warning' to be
     signalled in whichever thread the `function' was called in.

     Examples:

            ;;; good (assumes RELEASE-HANDLE is re-entrant)
            (let* ((handle (get-handle))
                   (object (make-object handle)))
             (finalize object (lambda () (release-handle handle)))
             object)

            ;;; bad, finalizer refers to object being finalized, causing
            ;;; it to be retained indefinitely
            (let* ((handle (get-handle))
                   (object (make-object handle)))
              (finalize object (lambda () (release-handle (object-handle object)))))

            ;;; bad, not re-entrant
            (defvar *rec* nil)

            (defun oops ()
             (when *rec*
               (error "recursive OOPS"))
             (let ((*rec* t))
               (gc))) ; or just cons enough to cause one

            (progn
              (finalize "oops" #'oops)
              (oops)) ; causes GC and re-entry to #'oops due to the finalizer
                      ; -> ERROR, caught, WARNING signalled

 -- Function: sb-ext:cancel-finalization object
     Cancel any finalization for `object'.

 -- Function: sb-ext:make-weak-pointer object
     Allocate and return a weak pointer which points to `object'.

 -- Function: sb-ext:weak-pointer-value weak-pointer
     If `weak-pointer' is valid, return the value of `weak-pointer' and
     `t'.  If the referent of `weak-pointer' has been garbage collected,
     returns the values `nil' and `nil'.

 -- Variable: sb-ext:*after-gc-hooks*
     Called after each garbage collection, except for garbage
     collections triggered during thread exits. In a multithreaded
     environment these hooks may run in any thread.


File: sbcl.info,  Node: Metaobject Protocol,  Next: Support For Unix,  Prev: Garbage Collection,  Up: Beyond the ANSI Standard

7.2 Metaobject Protocol
=======================

SBCL supports a metaobject protocol which is intended to be compatible
with AMOP; present exceptions to this (as distinct from current bugs)
are:

   * `compute-effective-method' only returns one value, not two.

     There is no record of what the second return value was meant to
     indicate, and apparently no clients for it.

   * The direct superclasses of `sb-mop:funcallable-standard-object' are
     `(function standard-object)', not `(standard-object function)'.

     This is to ensure that the `standard-object' class is the last of
     the standardized classes before `t' appearing in the class
     precedence list of `generic-function' and
     `standard-generic-function', as required by section 1.4.4.5 of the
     ANSI specification.

   * the arguments `:declare' and `:declarations' to
     `ensure-generic-function' are both accepted, with the leftmost
     argument defining the declarations to be stored and returned by
     `generic-function-declarations'.

     Where AMOP specifies `:declarations' as the keyword argument to
     `ensure-generic-function', the Common Lisp standard specifies
     `:declare'.  Portable code should use `:declare'.

   * although SBCL obeys the requirement in AMOP that
     `validate-superclass' should treat `standard-class' and
     `funcallable-standard-class' as compatible metaclasses, we impose
     an additional requirement at class finalization time: a class of
     metaclass `funcallable-standard-class' must have `function' in its
     superclasses, and a class of metaclass `standard-class' must not.

     After a class has been finalized, it is associated with a class
     prototype which is accessible by a standard mop function
     `sb-mop:class-prototype'.  The user can then ask whether this
     object is a `function' or not in several different ways: whether it
     is a function according to `typep'; whether its `class-of' is
     `subtypep' `function', or whether `function' appears in the
     superclasses of the class.  The additional consistency requirement
     comes from the desire to make all of these answers the same.

     The following class definitions are bad, and will lead to errors
     either immediately or if an instance is created:
          (defclass bad-object (funcallable-standard-object)
            ()
            (:metaclass standard-class))

          (defclass bad-funcallable-object (standard-object)
            ()
            (:metaclass funcallable-standard-class))
     The following definition is acceptable:
          (defclass mixin ()
            ((slot :initarg slot)))
          (defclass funcallable-object (funcallable-standard-object mixin)
            ()
            (:metaclass funcallable-standard-class))
     and leads to a class whose instances are funcallable and have one
     slot.

     Note that this requirement also applies to the class
     `sb-mop:funcallable-standard-object', which has metaclass
     `sb-mop:funcallable-standard-class' rather than `standard-class'
     as AMOP specifies.

   * the requirement that "No portable class C_p may inherit, by virtue
     of being a direct or indirect subclass of a specified class, any
     slot for which the name is a symbol accessible in the
     `common-lisp-user' package or exported by any package defined in
     the ANSI Common Lisp standard." is interpreted to mean that the
     standardized classes themselves should not have slots named by
     external symbols of public packages.

     The rationale behind the restriction is likely to be similar to
     the ANSI Common Lisp restriction on defining functions, variables
     and types named by symbols in the Common Lisp package: preventing
     two independent pieces of software from colliding with each other.

   * specializations of the `new-value' argument to `(setf
     sb-mop:slot-value-using-class)' are not allowed: all user-defined
     methods must have a specializer of the class `t'.

     This prohibition is motivated by a separation of layers: the
     `slot-value-using-class' family of functions is intended for use in
     implementing different and new slot allocation strategies, rather
     than in performing application-level dispatching.  Additionally,
     with this requirement, there is a one-to-one mapping between
     metaclass, class and slot-definition-class tuples and effective
     methods of `(setf slot-value-using-class)', which permits
     optimization of `(setf slot-value-using-class)''s discriminating
     function in the same manner as for `slot-value-using-class' and
     `slot-boundp-using-class'.

     Note that application code may specialize on the `new-value'
     argument of slot accessors.

   * the class named by the `name' argument to `ensure-class', if any,
     is only redefined if it is the proper name of that class;
     otherwise, a new class is created.

     This is consistent with the description of `ensure-class' in AMOP
     as the functional version of `defclass', which has this behaviour;
     however, it is not consistent with the weaker requirement in AMOP,
     which states that any class found by `find-class', no matter what
     its `class-name', is redefined.


   In addition, SBCL supports extensions to the Metaobject protocol from
AMOP; at present, they are:

   * compile-time support for generating specializer metaobjects from
     specializer names in `defmethod' forms is provided by the
     `make-method-specializers-form' function, which returns a form
     which, when evaluated in the lexical environment of the
     `defmethod', returns a list of specializer metaobjects.  This
     operator suffers from similar restrictions to those affecting
     `make-method-lambda', namely that the generic function must be
     defined when the `defmethod' form is expanded, so that the correct
     method of `make-method-specializers-form' is invoked.  The
     system-provided method on `make-method-specializers-form'
     generates a call to `find-class' for each symbol specializer name,
     and a call to `intern-eql-specializer' for each `(eql X)'
     specializer name.

   * run-time support for converting between specializer names and
     specializer metaobjects, mostly for the purposes of `find-method',
     is provided by `parse-specializer-using-class' and
     `unparse-specializer-using-class', which dispatch on their first
     argument, the generic function associated with a method with the
     given specializer.  The system-provided methods on those methods
     convert between classes and proper names and between lists of the
     form `(eql X)' and interned eql specializer objects.



File: sbcl.info,  Node: Support For Unix,  Next: Customization Hooks for Users,  Prev: Metaobject Protocol,  Up: Beyond the ANSI Standard

7.3 Support For Unix
====================

* Menu:

* Command-line arguments::
* Querying the process environment::
* Running external programs::


File: sbcl.info,  Node: Command-line arguments,  Next: Querying the process environment,  Up: Support For Unix

7.3.1 Command-line arguments
----------------------------

The UNIX command line can be read from the variable
`sb-ext:*posix-argv*'.


File: sbcl.info,  Node: Querying the process environment,  Next: Running external programs,  Prev: Command-line arguments,  Up: Support For Unix

7.3.2 Querying the process environment
--------------------------------------

The UNIX environment can be queried with the `sb-ext:posix-getenv'
function.

 -- Function: sb-ext:posix-getenv name
     Return the "value" part of the environment string "name=value"
     which corresponds to `name', or `nil' if there is none.


File: sbcl.info,  Node: Running external programs,  Prev: Querying the process environment,  Up: Support For Unix

7.3.3 Running external programs
-------------------------------

External programs can be run with `sb-ext:run-program'.  (1)

 -- Function: sb-ext:run-program program args &key env environment wait
          search pty input if-input-does-not-exist output
          if-output-exists error if-error-exists status-hook
     `run-program' creates a new process specified by the `program'
     argument. `args' are the standard arguments that can be passed to a
     program. For no arguments, use `nil' (which means that just the
     name of the program is passed as arg 0).

     The program arguments and the environment are encoded using the
     default external format for streams.

     `run-program' will return a `process' structure. See the `cmu'
     Common Lisp Users Manual for details about the `process' structure.

     Notes about Unix environments (as in the `:environment' and `:env'
     args):

        * The `sbcl' implementation of `run-program', like Perl and
          many other      programs, but unlike the original `cmu' `cl'
          implementation, copies      the Unix environment by default.

        * Running Unix programs from a setuid process, or in any other
             situation where the Unix environment is under the control
          of someone      else, is a mother lode of security problems.
          If you are contemplating      doing this, read about it
          first. (The Perl community has a lot of good
          documentation about this and other security issues in
          script-like      programs.)

        The `&key' arguments have the following meanings:

    _`:environment'_
          a list of STRINGs describing the new Unix environment
          (as in "man environ"). The default is to copy the environment
          of       the current process.

    _`:env'_
          an alternative lossy representation of the new Unix
          environment,       for compatibility with `cmu' `cl'

    _`:search'_
          Look for `program' in each of the directories in the child's
          $PATH       environment variable.  Otherwise an absolute
          pathname is required.

    _`:wait'_
          If non-NIL (default), wait until the created process
          finishes.  If       `nil', continue running Lisp until the
          program finishes.

    _`:pty'_
          Either `t', `nil', or a stream.  Unless `nil', the subprocess
          is established       under a `pty'.  If :pty is a stream, all
          output to this pty is sent to       this stream, otherwise
          the `process-pty' slot is filled in with a stream
          connected to pty that can read output and write input.

    _`:input'_
          Either `t', `nil', a pathname, a stream, or `:stream'.  If
          `t', the standard       input for the current process is
          inherited.  If `nil', /dev/null       is used.  If a
          pathname, the file so specified is used.  If a stream,
          all the input is read from that stream and sent to the
          subprocess.  If       `:stream', the `process-input' slot is
          filled in with a stream that sends       its output to the
          process. Defaults to `nil'.

    _`:if-input-does-not-exist' (when `:input' is the name of a file)_
          can be one of:          `:error' to generate an error
          `:create' to create an empty file          `nil' (the
          default) to return `nil' from `run-program'

    _`:output'_
          Either `t', `nil', a pathname, a stream, or `:stream'.  If
          `t', the standard       output for the current process is
          inherited.  If `nil', /dev/null       is used.  If a
          pathname, the file so specified is used.  If a stream,
          all the output from the process is written to this stream. If
               `:stream', the `process-output' slot is filled in with
          a stream that can       be read to get the output. Defaults
          to `nil'.

    _`:if-output-exists' (when `:output' is the name of a file)_
          can be one of:          `:error' (the default) to generate an
          error          `:supersede' to supersede the file with output
          from the program          `:append' to append output from the
          program to the file          `nil' to return `nil' from
          `run-program', without doing anything

    _`:error' and `:if-error-exists'_
          Same as `:output' and `:if-output-exists', except that
          `:error' can also be       specified as `:output' in which
          case all error output is routed to the       same place as
          normal output.

    _`:status-hook'_
          This is a function the system calls whenever the status of the
               process changes.  The function takes the process as an
          argument.


   When `sb-ext:run-program' is called with `wait' equal to NIL, an
instance of class SB-EXT:PROCESS is returned.  The following functions
are available for use with processes:

 -- Function: sb-ext:process-p object
     Returns true if argument is a `queue', `nil' otherwise.

 -- Function: sb-ext:process-input instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:process-output instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:process-error instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:process-alive-p process
     Return `t' if `process' is still alive, `nil' otherwise.

 -- Function: sb-ext:process-status process
     Return the current status of `process'.  The result is one of
     `:running',    `:stopped', `:exited', or `:signaled'.

 -- Function: sb-ext:process-wait process &optional check-for-stopped
     Wait for `process' to quit running for some reason. When
     `check-for-stopped' is `t', also returns when `process' is
     stopped. Returns `process'.

 -- Function: sb-ext:process-exit-code instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:process-core-dumped instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:process-close process
     Close all streams connected to `process' and stop maintaining the
     status slot.

 -- Function: sb-ext:process-kill process signal &optional whom
     Hand `signal' to `process'. If `whom' is `:pid', use the kill Unix
     system call. If    `whom' is `:process-group', use the killpg Unix
     system call. If `whom' is    `:pty-process-group' deliver the
     signal to whichever process group is    currently in the
     foreground.

   ---------- Footnotes ----------

   (1) In SBCL versions prior to 1.0.13, `sb-ext:run-program' searched
for executables in a manner somewhat incompatible with other languages.
As of this version, SBCL uses the system library routine `execvp(3)',
and no longer contains the function, `find-executable-in-search-path',
which implemented the old search.  Users who need this function may
find it in `run-program.lisp' versions 1.67 and earlier in SBCL's CVS
repository here
`http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log'.
However, we caution such users that this search routine finds
executables that system library routines do not.


File: sbcl.info,  Node: Customization Hooks for Users,  Next: Tools To Help Developers,  Prev: Support For Unix,  Up: Beyond the ANSI Standard

7.4 Customization Hooks for Users
=================================

The toplevel repl prompt may be customized, and the function that reads
user input may be replaced completely.

   The behaviour of `require' when called with only one argument is
implementation-defined.  In SBCL, `require' behaves in the following
way:

 -- Function: cl:require module-name &optional pathnames
     Loads a module, unless it already has been loaded. `pathnames', if
     supplied,    is a designator for a list of pathnames to be loaded
     if the module    needs to be. If `pathnames' is not supplied,
     functions from the list    `*module-provider-functions*' are
     called in order with `module-name'    as an argument, until one of
     them returns non-NIL.  User code is    responsible for calling
     `provide' to indicate a successful load of the    module.

 -- Variable: sb-ext:*module-provider-functions*
     See function documentation for `require'.

   Although SBCL does not provide a resident editor, the `ed' function
can be customized to hook into user-provided editing mechanisms as
follows:

 -- Function: cl:ed &optional x
     Starts the editor (on a file or a function if named).  Functions
     from the list `*ed-functions*' are called in order with `x' as an
     argument until one of them returns non-NIL; these functions are
     responsible for signalling a `file-error' to indicate failure to
     perform an operation on the file system.

 -- Variable: sb-ext:*ed-functions*
     See function documentation for `ed'.

   Conditions of type `warning' and `style-warning' are sometimes
signaled at runtime, especially during execution of Common Lisp
defining forms such as `defun', `defmethod', etc.  To muffle these
warnings at runtime, SBCL provides a variable
`sb-ext:*muffled-warnings*':

 -- Variable: sb-ext:*muffled-warnings*
     A type that ought to specify a subtype of `warning'.  Whenever a
     warning is signaled, if the warning if of this type and is not
     handled by any other handler, it will be muffled.


File: sbcl.info,  Node: Tools To Help Developers,  Next: Resolution of Name Conflicts,  Prev: Customization Hooks for Users,  Up: Beyond the ANSI Standard

7.5 Tools To Help Developers
============================

SBCL provides a profiler and other extensions to the ANSI `trace'
facility.  For more information, see *Note Macro common-lisp:trace::.

   The debugger supports a number of options. Its documentation is
accessed by typing `help' at the debugger prompt. *Note Debugger::.

   Documentation for `inspect' is accessed by typing `help' at the
`inspect' prompt.


File: sbcl.info,  Node: Resolution of Name Conflicts,  Next: Hash Table Extensions,  Prev: Tools To Help Developers,  Up: Beyond the ANSI Standard

7.6 Resolution of Name Conflicts
================================

The ANSI standard (section 11.1.1.2.5) requires that name conflicts in
packages be resolvable in favour of any of the conflicting symbols.  In
the interactive debugger, this is achieved by prompting for the symbol
in whose favour the conflict should be resolved; for programmatic use,
the `sb-ext:resolve-conflict' restart should be invoked with one
argument, which should be a member of the list returned by the condition
accessor `sb-ext:name-conflict-symbols'.


File: sbcl.info,  Node: Hash Table Extensions,  Next: Miscellaneous Extensions,  Prev: Resolution of Name Conflicts,  Up: Beyond the ANSI Standard

7.7 Hash Table Extensions
=========================

Hash table extensions supported by SBCL are all controlled by keyword
arguments to `make-hash-table'.

 -- Function: cl:make-hash-table &key test size rehash-size
          rehash-threshold hash-function weakness synchronized
     Create and return a new hash table. The keywords are as follows:

    _`:test'_
          Determines how keys are compared. Must a designator for one
          of the     standard hash table tests, or a hash table test
          defined using     `sb-ext:define-hash-table-test'.
          Additionally, when an explicit     `hash-function' is
          provided (see below), any two argument equivalence
          predicate can be used as the `test'.

    _`:size'_
          A hint as to how many elements will be put in this hash table.

    _`:rehash-size'_
          Indicates how to expand the table when it fills up. If an
          integer, add     space for that many elements. If a floating
          point number (which must be     greater than 1.0), multiply
          the size by that amount.

    _`:rehash-threshold'_
          Indicates how dense the table can become before forcing a
          rehash. Can be     any positive number <=1, with density
          approaching zero as the threshold     approaches 0. Density 1
          means an average of one entry per bucket.

    _`:hash-function'_
          If `nil' (the default), a hash function based on the `test'
          argument is used,     which then must be one of the
          standardized hash table test functions, or     one for which
          a default hash function has been defined using
          `sb-ext:define-hash-table-test'. If `hash-function' is
          specified, the `test'     argument can be any two argument
          predicate consistent with it. The     `hash-function' is
          expected to return a non-negative fixnum hash code.

    _`:weakness'_
          If `nil' (the default) it is a normal non-weak hash table. If
          one     of `:key', `:value', `:key-and-value',
          `:key-or-value' it is a weak hash table.      Depending on
          the type of weakness the lack of references to the key and
          the value may allow for removal of the entry. If `weakness'
          is `:key' and the     key would otherwise be garbage the
          entry is eligible for removal from the     hash table.
          Similarly, if `weakness' is `:value' the life of an entry
          depends     on its value's references. If `weakness' is
          `:key-and-value' and either the     key or the value would
          otherwise be garbage the entry can be removed. If
          `weakness' is `:key-or-value' and both the key and the value
          would otherwise     be garbage the entry can be removed.

    _`:synchronized'_
          If `nil' (the default), the hash-table may have multiple
          concurrent readers,     but results are undefined if a thread
          writes to the hash-table     concurrently with another reader
          or writer. If `t', all concurrent accesses     are safe, but
          note that `clhs' 3.6 (Traversal Rules and Side Effects)
          remains in force. See also: `sb-ext:with-locked-hash-table'.
          This keyword     argument is experimental, and may change
          incompatibly or be removed in the     future.


 -- Macro: sb-ext:define-hash-table-test name hash-function
     Defines `name' as a new kind of hash table test for use with the
     `:test' argument to `make-hash-table', and associates a default
     `hash-function' with it.

     `name' must be a symbol naming a global two argument equivalence
     predicate.  Afterwards both `'name' and `#'name' can be used with
     `:test' argument. In both cases `hash-table-test' will return the
     symbol `name'.

     `hash-function' must be a symbol naming a global hash function
     consistent with the predicate, or be a `lambda' form implementing
     one in the current lexical environment. The hash function must
     compute the same hash code for any two objects for which `name'
     returns true, and subsequent calls with already hashed objects
     must always return the same hash code.

     Note: The `:hash-function' keyword argument to `make-hash-table'
     can be used to override the specified default hash-function.

     Attempting to define `name' in a locked package as hash-table test
     causes a package lock violation.

     Examples:

            ;;; 1.

            ;; We want to use objects of type FOO as keys (by their
            ;; names.) EQUALP would work, but would make the names
            ;; case-insensitive -- wich we don't want.
            (defstruct foo (name nil :type (or null string)))

            ;; Define an equivalence test function and a hash function.
            (defun foo-name= (f1 f2) (equal (foo-name f1) (foo-name f2)))
            (defun sxhash-foo-name (f) (sxhash (foo-name f)))

            (define-hash-table-test foo-name= sxhash-foo-name)

            ;; #'foo-name would work too.
            (defun make-foo-table () (make-hash-table :test 'foo-name=))

            ;;; 2.

            (defun == (x y) (= x y))

            (define-hash-table-test ==
              (lambda (x)
                ;; Hash codes must be consistent with test, so
                ;; not (SXHASH X), since
                ;;   (= 1 1.0)                   => T
                ;;   (= (SXHASH 1) (SXHASH 1.0)) => NIL
                ;; Note: this doesn't deal with complex numbers or
                ;; bignums too large to represent as double floats.
                (sxhash (coerce x 'double-float))))

            ;; #'== would work too
            (defun make-number-table () (make-hash-table :test '==))

 -- Macro: sb-ext:with-locked-hash-table (hash-table) &body body
     Limits concurrent accesses to `hash-table' for the duration of
     `body'.  If `hash-table' is synchronized, `body' will execute with
     exclusive ownership of the table. If `hash-table' is not
     synchronized, `body' will execute with other
     `with-locked-hash-table' bodies excluded `--' exclusion of
     hash-table accesses not surrounded by `with-locked-hash-table' is
     unspecified.

 -- Function: sb-ext:hash-table-synchronized-p instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-ext:hash-table-weakness instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.


File: sbcl.info,  Node: Miscellaneous Extensions,  Next: Stale Extensions,  Prev: Hash Table Extensions,  Up: Beyond the ANSI Standard

7.8 Miscellaneous Extensions
============================

 -- Function: sb-ext:array-storage-vector array
     Returns the underlying storage vector of `array', which must be a
     non-displaced array.

     In `sbcl', if `array' is a of type (SIMPLE-ARRAY `*' (*)), it is
     its own storage vector. Multidimensional arrays, arrays with fill
     pointers, and adjustable arrays have an underlying storage vector
     with the same `array-element-type' as `array', which this function
     returns.

     Important note: the underlying vector is an implementation detail.
     Even though this function exposes it, changes in the
     implementation may cause this function to be removed without
     further warning.


File: sbcl.info,  Node: Stale Extensions,  Next: Efficiency Hacks,  Prev: Miscellaneous Extensions,  Up: Beyond the ANSI Standard

7.9 Stale Extensions
====================

SBCL has inherited from CMUCL various hooks to allow the user to tweak
and monitor the garbage collection process. These are somewhat stale
code, and their interface might need to be cleaned up. If you have
urgent need of them, look at the code in `src/code/gc.lisp' and bring
it up on the developers' mailing list.

   SBCL has various hooks inherited from CMUCL, like
`sb-ext:float-denormalized-p', to allow a program to take advantage of
IEEE floating point arithmetic properties which aren't conveniently or
efficiently expressible using the ANSI standard. These look good, and
their interface looks good, but IEEE support is slightly broken due to
a stupid decision to remove some support for infinities (because it
wasn't in the ANSI spec and it didn't occur to me that it was in the
IEEE spec). If you need this stuff, take a look at the code and bring
it up on the developers' mailing list.


File: sbcl.info,  Node: Efficiency Hacks,  Prev: Stale Extensions,  Up: Beyond the ANSI Standard

7.10 Efficiency Hacks
=====================

The `sb-ext:purify' function causes SBCL first to collect all garbage,
then to mark all uncollected objects as permanent, never again
attempting to collect them as garbage. This can cause a large increase
in efficiency when using a primitive garbage collector, or a more
moderate increase in efficiency when using a more sophisticated garbage
collector which is well suited to the program's memory usage pattern. It
also allows permanent code to be frozen at fixed addresses, a
precondition for using copy-on-write to share code between multiple Lisp
processes.  This is less important with modern generational garbage
collectors, but not all SBCL platforms use such a garbage collector.

 -- Function: sb-ext:purify &key root-structures environment-name
     This function optimizes garbage collection by moving all currently
     live    objects into non-collected storage. `root-structures' is
     an optional list of    objects which should be copied first to
     maximize locality.

     `defstruct' structures defined with the (:PURE T) option are moved
     into    read-only storage, further reducing `gc' cost. List and
     vector slots of pure    structures are also moved into read-only
     storage.

     `environment-name' is gratuitous documentation for compacted
     version of the    current global environment (as seen in
     `sb'!`c::*info-environment*'.) If `nil' is    supplied, then
     environment compaction is inhibited.

     This function is a no-op on platforms using the generational
     garbage    collector (x86, x86-64, ppc).

   The `sb-ext:truly-the' special form declares the type of the result
of the operations, producing its argument; the declaration is not
checked. In short: don't use it.

 -- Special Operator: sb-ext:truly-the value-type form
     Specifies that the values returned by `form' conform to the
     `value-type', and causes the compiler to trust this information
     unconditionally.

     Consequences are undefined if any result is not of the declared
     type `--' typical symptoms including memory corruptions. Use with
     great care.

   The `sb-ext:freeze-type' declaration declares that a type will never
change, which can make type testing (`typep', etc.) more efficient for
structure types.

   The `sb-ext:constant-function' declaration specifies that a function
will always return the same value for the same arguments, which may
allow the compiler to optimize calls to it. This is appropriate for
functions like `sqrt', but is _not_ appropriate for functions like
`aref', which can change their return values when the underlying data
are changed.


File: sbcl.info,  Node: Foreign Function Interface,  Next: Pathnames,  Prev: Beyond the ANSI Standard,  Up: Top

8 Foreign Function Interface
****************************

This chapter describes SBCL's interface to C programs and libraries
(and, since C interfaces are a sort of _lingua franca_ of the Unix
world, to other programs and libraries in general.)

     Note: In the modern Lisp world, the usual term for this
     functionality is Foreign Function Interface, or FFI, where despite
     the mention of "function" in this term, FFI also refers to direct
     manipulation of C data structures as well as functions. The
     traditional CMUCL terminology is Alien Interface, and while that
     older terminology is no longer used much in the system
     documentation, it still reflected in names in the implementation,
     notably in the name of the `SB-ALIEN' package.

* Menu:

* Introduction to the Foreign Function Interface::
* Foreign Types::
* Operations On Foreign Values::
* Foreign Variables::
* Foreign Data Structure Examples::
* Loading Shared Object Files::
* Foreign Function Calls::
* Step-By-Step Example of the Foreign Function Interface::


File: sbcl.info,  Node: Introduction to the Foreign Function Interface,  Next: Foreign Types,  Up: Foreign Function Interface

8.1 Introduction to the Foreign Function Interface
==================================================

Because of Lisp's emphasis on dynamic memory allocation and garbage
collection, Lisp implementations use non-C-like memory representations
for objects.  This representation mismatch creates friction when a Lisp
program must share objects with programs which expect C data.  There
are three common approaches to establishing communication:

   * The burden can be placed on the foreign program (and programmer) by
     requiring the knowledge and use of the representations used
     internally by the Lisp implementation.  This can require a
     considerable amount of "glue" code on the C side, and that code
     tends to be sensitively dependent on the internal implementation
     details of the Lisp system.

   * The Lisp system can automatically convert objects back and forth
     between the Lisp and foreign representations.  This is convenient,
     but translation becomes prohibitively slow when large or complex
     data structures must be shared. This approach is supported by the
     SBCL FFI, and used automatically by the when passing integers and
     strings.

   * The Lisp program can directly manipulate foreign objects through
     the use of extensions to the Lisp language.


   SBCL, like CMUCL before it, relies primarily on the automatic
conversion and direct manipulation approaches. The `SB-ALIEN' package
provides a facility wherein foreign values of simple scalar types are
automatically converted and complex types are directly manipulated in
their foreign representation.  Additionally the lower-level System Area
Pointers (or SAPs) can be used where necessary to provide untyped
access to foreign memory.

   Any foreign objects that can't automatically be converted into Lisp
values are represented by objects of type `alien-value'.  Since Lisp is
a dynamically typed language, even foreign objects must have a run-time
type; this type information is provided by encapsulating the raw
pointer to the foreign data within an `alien-value' object.

   The type language and operations on foreign types are intentionally
similar to those of the C language.


File: sbcl.info,  Node: Foreign Types,  Next: Operations On Foreign Values,  Prev: Introduction to the Foreign Function Interface,  Up: Foreign Function Interface

8.2 Foreign Types
=================

Alien types have a description language based on nested list structure.
For example the C type

     struct foo {
         int a;
         struct foo *b[100];
     };

   has the corresponding SBCL FFI type

     (struct foo
       (a int)
       (b (array (* (struct foo)) 100)))

* Menu:

* Defining Foreign Types::
* Foreign Types and Lisp Types::
* Foreign Type Specifiers::


File: sbcl.info,  Node: Defining Foreign Types,  Next: Foreign Types and Lisp Types,  Up: Foreign Types

8.2.1 Defining Foreign Types
----------------------------

Types may be either named or anonymous.  With structure and union
types, the name is part of the type specifier, allowing recursively
defined types such as:

     (struct foo (a (* (struct foo))))

   An anonymous structure or union type is specified by using the name
`nil'.  The `with-alien' macro defines a local scope which "captures"
any named type definitions.  Other types are not inherently named, but
can be given named abbreviations using the `define-alien-type' macro.


File: sbcl.info,  Node: Foreign Types and Lisp Types,  Next: Foreign Type Specifiers,  Prev: Defining Foreign Types,  Up: Foreign Types

8.2.2 Foreign Types and Lisp Types
----------------------------------

The foreign types form a subsystem of the SBCL type system.  An `alien'
type specifier provides a way to use any foreign type as a Lisp type
specifier.  For example,

     (typep FOO '(alien (* int)))

   can be used to determine whether FOO is a pointer to a foreign
`int'. `alien' type specifiers can be used in the same ways as ordinary
Lisp type specifiers (like `string'.) Alien type declarations are
subject to the same precise type checking as any other declaration.
*Note Precise Type Checking::.

   Note that the type identifiers used in the foreign type system
overlap with native Lisp type specifiers in some cases.  For example,
the type specifier `(alien single-float)' is identical to
`single-float', since foreign floats are automatically converted to
Lisp floats.  When `type-of' is called on an alien value that is not
automatically converted to a Lisp value, then it will return an `alien'
type specifier.


File: sbcl.info,  Node: Foreign Type Specifiers,  Prev: Foreign Types and Lisp Types,  Up: Foreign Types

8.2.3 Foreign Type Specifiers
-----------------------------

Note: All foreign type names are exported from the `sb-alien' package.
Some foreign type names are also symbols in the `common-lisp' package,
in which case they are reexported from the `sb-alien' package, so that
e.g. it is legal to refer to `sb-alien:single-float'.

   These are the basic foreign type specifiers:

   * The foreign type specifier `(* FOO)' describes a pointer to an
     object of type FOO.  A pointed-to type FOO of `t' indicates a
     pointer to anything, similar to `void *' in ANSI C. A null alien
     pointer can be detected with the `sb-alien:null-alien' function.

   * The foreign type specifier `(array FOO &rest dimensions)'
     describes array of the specified `dimensions', holding elements of
     type FOO. Note that (unlike in C) `(* FOO)' and `(array FOO)' are
     considered to be different types when type checking is done. If
     equivalence of pointer and array types is desired, it may be
     explicitly coerced using `sb-alien:cast'.

     Arrays are accessed using `sb-alien:deref', passing the indices as
     additional arguments.  Elements are stored in column-major order
     (as in C), so the first dimension determines only the size of the
     memory block, and not the layout of the higher dimensions.  An
     array whose first dimension is variable may be specified by using
     `nil' as the first dimension.  Fixed-size arrays can be allocated
     as array elements, structure slots or `sb-alien:with-alien'
     variables. Dynamic arrays can only be allocated using
     `sb-alien:make-alien'.

   * The foreign type specifier `(sb-alien:struct NAME &rest FIELDS)'
     describes a structure type with the specified NAME and FIELDS.
     Fields are allocated at the same offsets used by the
     implementation's C compiler, as guessed by the SBCL internals. An
     optional `:alignment' keyword argument can be specified for each
     field to explicitly control the alignment of a field. If NAME is
     `nil' then the structure is anonymous.

     If a named foreign `struct' specifier is passed to
     `define-alien-type' or `with-alien', then this defines,
     respectively, a new global or local foreign structure type.  If no
     FIELDS are specified, then the fields are taken from the current
     (local or global) alien structure type definition of NAME.

   * The foreign type specifier `(sb-alien:union NAME &rest FIELDS)' is
     similar to `sb-alien:struct', but describes a union type.  All
     fields are allocated at the same offset, and the size of the union
     is the size of the largest field.  The programmer must determine
     which field is active from context.

   * The foreign type specifier `(sb-alien:enum NAME &rest SPECS)'
     describes an enumeration type that maps between integer values and
     symbols. If NAME is `nil', then the type is anonymous.  Each
     element of the SPECS list is either a Lisp symbol, or a list
     `(SYMBOL VALUE)'.  VALUE is an integer. If VALUE is not supplied,
     then it defaults to one greater than the value for the preceding
     spec (or to zero if it is the first spec).

   * The foreign type specifier `(sb-alien:signed &optional BITS)'
     specifies a signed integer with the specified number of BITS
     precision. The upper limit on integer precision is determined by
     the machine's word size. If BITS is not specified, the maximum
     size will be used.

   * The foreign type specifier `(integer &optional BITS)' is
     equivalent to the corresponding type specifier using
     `sb-alien:signed' instead of `integer'.

   * The foreign type specifier `(sb-alien:unsigned &optional BITS)' is
     like corresponding type specifier using `sb-alien:signed' except
     that the variable is treated as an unsigned integer.

   * The foreign type specifier `(boolean &optional BITS)' is similar
     to an enumeration type, but maps from Lisp `nil' and `t' to C `0'
     and `1' respectively. BITS determines the amount of storage
     allocated to hold the truth value.

   * The foreign type specifier `single-float' describes a
     floating-point number in IEEE single-precision format.

   * The foreign type specifier `double-float' describes a
     floating-point number in IEEE double-precision format.

   * The foreign type specifier `(function RESULT-TYPE &rest
     ARG-TYPES)' describes a foreign function that takes arguments of
     the specified ARG-TYPES and returns a result of type RESULT-TYPE.
     Note that the only context where a foreign `function' type is
     directly specified is in the argument to `sb-alien:alien-funcall'.
     In all other contexts, foreign functions are represented by
     foreign function pointer types: `(* (function ...))'.

   * The foreign type specifier `sb-alien:system-area-pointer'
     describes a pointer which is represented in Lisp as a
     `system-area-pointer' object.  SBCL exports this type from
     `sb-alien' because CMUCL did, but tentatively (as of the first
     draft of this section of the manual, SBCL 0.7.6) it is deprecated,
     since it doesn't seem to be required by user code.

   * The foreign type specifier `sb-alien:void' is used in function
     types to declare that no useful value is returned.  Using
     `alien-funcall' to call a `void' foreign function will return zero
     values.

   * The foreign type specifier `(sb-alien:c-string &key external-format
     element-type)' is similar to `(* char)', but is interpreted as a
     null-terminated string, and is automatically converted into a Lisp
     string when accessed; or if the pointer is C `NULL' or `0', then
     accessing it gives Lisp `nil'.

     External format conversion is automatically done when Lisp strings
     are passed to foreign code, or when foreign strings are passed to
     Lisp code.  If the type specifier has an explicit
     `external-format', that external format will be used. Otherwise a
     default external format that has been determined at SBCL startup
     time based on the current locale settings will be used. For
     example, when the following alien routine is called, the Lisp
     string given as argument is converted to an `ebcdic' octet
     representation.

          (define-alien-routine test int (str (c-string :external-format :ebcdic-us)))

     Lisp strings of type `base-string' are stored with a trailing NUL
     termination, so no copying (either by the user or the
     implementation) is necessary when passing them to foreign code,
     assuming that the `external-format' and `element-type' of the
     `c-string' type are compatible with the internal representation of
     the string. For an SBCL built with Unicode support that means an
     `external-format' of `:ascii' and an `element-type' of
     `base-char'. Without Unicode support the `external-format' can
     also be `:iso-8859-1', and the `element-type' can also be
     `character'. If the `external-format' or `element-type' is not
     compatible, or the string is a `(simple-array character (*))',
     this data is copied by the implementation as required.

     Assigning a Lisp string to a `c-string' structure field or
     variable stores the contents of the string to the memory already
     pointed to by that variable.  When a foreign object of type `(*
     char)' is assigned to a `c-string', then the `c-string' pointer is
     assigned to.  This allows `c-string' pointers to be initialized.
     For example:

          (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"

          (define-alien-type nil (struct foo (str c-string)))

          (defun make-foo (str)
            (let ((my-foo (make-alien (struct foo))))
              (setf (slot my-foo 'str) (make-alien char (length str))
                    (slot my-foo 'str) str)
              my-foo))

     Storing Lisp `NIL' in a `c-string' writes C `NULL' to the variable.

   * `sb-alien' also exports translations of these C type specifiers as
     foreign type specifiers: `sb-alien:char', `sb-alien:short',
     `sb-alien:int', `sb-alien:long', `sb-alien:unsigned-char',
     `sb-alien:unsigned-short', `sb-alien:unsigned-int',
     `sb-alien:unsigned-long', `sb-alien:float', and `sb-alien:double'.



File: sbcl.info,  Node: Operations On Foreign Values,  Next: Foreign Variables,  Prev: Foreign Types,  Up: Foreign Function Interface

8.3 Operations On Foreign Values
================================

This section describes how to read foreign values as Lisp values, how
to coerce foreign values to different kinds of foreign values, and how
to dynamically allocate and free foreign variables.

* Menu:

* Accessing Foreign Values::
* Coercing Foreign Values::
* Foreign Dynamic Allocation::


File: sbcl.info,  Node: Accessing Foreign Values,  Next: Coercing Foreign Values,  Up: Operations On Foreign Values

8.3.1 Accessing Foreign Values
------------------------------

 -- Function: sb-alien:deref POINTER-OR-ARRAY &rest INDICES
     The `sb-alien:deref' function returns the value pointed to by a
     foreign pointer, or the value of a foreign array element. When
     dereferencing a pointer, an optional single index can be specified
     to give the equivalent of C pointer arithmetic; this index is
     scaled by the size of the type pointed to. When dereferencing an
     array, the number of indices must be the same as the number of
     dimensions in the array type. `deref' can be set with `setf' to
     assign a new value.

 -- Function: sb-alien:slot STRUCT-OR-UNION SLOT-NAME
     The `sb-alien:slot' function extracts the value of the slot named
     SLOT-NAME from a foreign `struct' or `union'. If STRUCT-OR-UNION
     is a pointer to a structure or union, then it is automatically
     dereferenced.  `sb-alien:slot' can be set with `setf' to assign a
     new value. Note that SLOT-NAME is evaluated, and need not be a
     compile-time constant (but only constant slot accesses are
     efficiently compiled).

8.3.1.1 Untyped memory
......................

As noted at the beginning of the chapter, the System Area Pointer
facilities allow untyped access to foreign memory.  SAPs can be
converted to and from the usual typed foreign values using `sap-alien'
and `alien-sap' (described elsewhere), and also to and from integers -
raw machine addresses.  They should thus be used with caution;
corrupting the Lisp heap or other memory with SAPs is trivial.

 -- Function: sb-sys:int-sap MACHINE-ADDRESS
     Creates a SAP pointing at the virtual address MACHINE-ADDRESS.

 -- Function: sb-sys:sap-ref-32 SAP OFFSET
     Access the value of the memory location at OFFSET bytes from SAP.
     This form may also be used with `setf' to alter the memory at that
     location.

 -- Function: sb-sys:sap= SAP1 SAP2
     Compare SAP1 and SAP2 for equality.

   Similarly named functions exist for accessing other sizes of word,
other comparisons, and other conversions.  The reader is invited to use
`apropos' and `describe' for more details

     (apropos "sap" :sb-sys)


File: sbcl.info,  Node: Coercing Foreign Values,  Next: Foreign Dynamic Allocation,  Prev: Accessing Foreign Values,  Up: Operations On Foreign Values

8.3.2 Coercing Foreign Values
-----------------------------

 -- Function: sb-alien:addr ALIEN-EXPR
     The `sb-alien:addr' macro returns a pointer to the location
     specified by ALIEN-EXPR, which must be either a foreign variable,
     a use of `sb-alien:deref', a use of `sb-alien:slot', or a use of
     `sb-alien:extern-alien'.

 -- Function: sb-alien:cast FOREIGN-VALUE NEW-TYPE
     The `sb-alien:cast' macro converts FOREIGN-VALUE to a new foreign
     value with the specified NEW-TYPE. Both types, old and new, must
     be foreign pointer, array or function types.  Note that the
     resulting Lisp foreign variable object is not `eq' to the
     argument, but it does refer to the same foreign data bits.

 -- Function: sb-alien:sap-alien SAP TYPE
     The `sb-alien:sap-alien' function converts SAP (a system area
     pointer) to a foreign value with the specified TYPE. TYPE is not
     evaluated.

     The TYPE must be some foreign pointer, array, or record type.

 -- Function: sb-alien:alien-sap FOREIGN-VALUE
     The `sb-alien:alien-sap' function returns the SAP which points to
     ALIEN-VALUE's data.

     The FOREIGN-VALUE must be of some foreign pointer, array, or
     record type.


File: sbcl.info,  Node: Foreign Dynamic Allocation,  Prev: Coercing Foreign Values,  Up: Operations On Foreign Values

8.3.3 Foreign Dynamic Allocation
--------------------------------

Lisp code can call the C standard library functions `malloc' and `free'
to dynamically allocate and deallocate foreign variables. The Lisp code
shares the same allocator with foreign C code, so it's OK for foreign
code to call `free' on the result of Lisp `sb-alien:make-alien', or for
Lisp code to call `sb-alien:free-alien' on foreign objects allocated by
C code.

 -- Macro: sb-alien:make-alien TYPE SIZE
     The `sb-alien:make-alien' macro returns a dynamically allocated
     foreign value of the specified TYPE (which is not evaluated.)  The
     allocated memory is not initialized, and may contain arbitrary
     junk.  If supplied, SIZE is an expression to evaluate to compute
     the size of the allocated object.  There are two major cases:

        * When TYPE is a foreign array type, an array of that type is
          allocated and a pointer to it is returned.  Note that you
          must use `deref' to change the result to an array before you
          can use `deref' to read or write elements:

               (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
               (defvar *foo* (make-alien (array char 10)))
               (type-of *foo*) => (alien (* (array (signed 8) 10)))
               (setf (deref (deref foo) 0) 10) => 10

          If supplied, SIZE is used as the first dimension for the
          array.

        * When TYPE is any other foreign type, then an object for that
          type is allocated, and a pointer to it is returned.  So
          `(make-alien int)' returns a `(* int)'.  If SIZE is
          specified, then a block of that many objects is allocated,
          with the result pointing to the first one.



 -- Function: sb-alien:free-alien FOREIGN-VALUE
     The `sb-alien:free-alien' function frees the storage for
     FOREIGN-VALUE, which must have been allocated with Lisp
     `make-alien' or C `malloc'.

     See also the `sb-alien:with-alien' macro, which allocates foreign
     values on the stack.


File: sbcl.info,  Node: Foreign Variables,  Next: Foreign Data Structure Examples,  Prev: Operations On Foreign Values,  Up: Foreign Function Interface

8.4 Foreign Variables
=====================

Both local (stack allocated) and external (C global) foreign variables
are supported.

* Menu:

* Local Foreign Variables::
* External Foreign Variables::


File: sbcl.info,  Node: Local Foreign Variables,  Next: External Foreign Variables,  Up: Foreign Variables

8.4.1 Local Foreign Variables
-----------------------------

 -- Macro: sb-alien:with-alien VAR-DEFINITIONS &body BODY
     The `with-alien' macro establishes local foreign variables with
     the specified alien types and names.  This form is analogous to
     defining a local variable in C: additional storage is allocated,
     and the initial value is copied.  This form is less analogous to
     `LET'-allocated Lisp variables, since the variables can't be
     captured in closures: they live only for the dynamic extent of the
     body, and referring to them outside is a gruesome error.

     The VAR-DEFINITIONS argument is a list of variable definitions,
     each of the form
          (NAME TYPE &optional INITIAL-VALUE)

     The names of the variables are established as symbol-macros; the
     bindings have lexical scope, and may be assigned with `setq' or
     `setf'.

     The `with-alien' macro also establishes a new scope for named
     structures and unions.  Any TYPE specified for a variable may
     contain named structure or union types with the slots specified.
     Within the lexical scope of the binding specifiers and body, a
     locally defined foreign structure type FOO can be referenced by
     its name using `(struct FOO)'.


File: sbcl.info,  Node: External Foreign Variables,  Prev: Local Foreign Variables,  Up: Foreign Variables

8.4.2 External Foreign Variables
--------------------------------

External foreign names are strings, and Lisp names are symbols. When an
external foreign value is represented using a Lisp variable, there must
be a way to convert from one name syntax into the other. The macros
`extern-alien', `define-alien-variable' and `define-alien-routine' use
this conversion heuristic:

   * Alien names are converted to Lisp names by uppercasing and
     replacing underscores with hyphens.

   * Conversely, Lisp names are converted to alien names by lowercasing
     and replacing hyphens with underscores.

   * Both the Lisp symbol and alien string names may be separately
     specified by using a list of the form

          (alien-string lisp-symbol)


 -- Macro: sb-alien:define-alien-variable NAME TYPE
     The `define-alien-variable' macro defines NAME as an external
     foreign variable of the specified foreign `type'.  NAME and `type'
     are not evaluated.  The Lisp name of the variable (see above)
     becomes a global alien variable.  Global alien variables are
     effectively "global symbol macros"; a reference to the variable
     fetches the contents of the external variable.  Similarly, setting
     the variable stores new contents - the new contents must be of the
     declared `type'. Someday, they may well be implemented using the
     ANSI `define-symbol-macro' mechanism, but as of SBCL 0.7.5, they
     are still implemented using an older more-or-less parallel
     mechanism inherited from CMUCL.

     For example, to access a C-level counter FOO, one could write

          (define-alien-variable "foo" int)
          ;; Now it is possible to get the value of the C variable foo simply by
          ;; referencing that Lisp variable:
          (print foo)
          (setf foo 14)
          (incf foo)

 -- Function: sb-alien:get-errno
     Since in modern C libraries, the `errno' "variable" is typically
     no longer a variable, but some bizarre artificial construct which
     behaves superficially like a variable within a given thread, it
     can no longer reliably be accessed through the ordinary
     `define-alien-variable' mechanism. Instead, SBCL provides the
     operator `sb-alien:get-errno' to allow Lisp code to read it.

 -- Macro: sb-alien:extern-alien NAME TYPE
     The `extern-alien' macro returns an alien with the specified TYPE
     which points to an externally defined value.  NAME is not
     evaluated, and may be either a string or a symbol.  TYPE is an
     unevaluated alien type specifier.


File: sbcl.info,  Node: Foreign Data Structure Examples,  Next: Loading Shared Object Files,  Prev: Foreign Variables,  Up: Foreign Function Interface

8.5 Foreign Data Structure Examples
===================================

Now that we have alien types, operations and variables, we can
manipulate foreign data structures.  This C declaration

     struct foo {
         int a;
         struct foo *b[100];
     };

   can be translated into the following alien type:

     (define-alien-type nil
       (struct foo
         (a int)
         (b (array (* (struct foo)) 100))))

   Once the `foo' alien type has been defined as above, the C expression

     struct foo f;
     f.b[7].a;

   can be translated in this way:

     (with-alien ((f (struct foo)))
       (slot (deref (slot f 'b) 7) 'a)
       ;;
       ;; Do something with f...
       )

   Or consider this example of an external C variable and some accesses:

     struct c_struct {
             short x, y;
             char a, b;
             int z;
             c_struct *n;
     };
     extern struct c_struct *my_struct;
     my_struct->x++;
     my_struct->a = 5;
     my_struct = my_struct->n;

   which can be manipulated in Lisp like this:

     (define-alien-type nil
       (struct c-struct
               (x short)
               (y short)
               (a char)
               (b char)
               (z int)
               (n (* c-struct))))
     (define-alien-variable "my_struct" (* c-struct))
     (incf (slot my-struct 'x))
     (setf (slot my-struct 'a) 5)
     (setq my-struct (slot my-struct 'n))


File: sbcl.info,  Node: Loading Shared Object Files,  Next: Foreign Function Calls,  Prev: Foreign Data Structure Examples,  Up: Foreign Function Interface

8.6 Loading Shared Object Files
===============================

Foreign object files can be loaded into the running Lisp process by
calling `load-shared-object'.

 -- Function: sb-alien:load-shared-object pathname &key dont-save
     Load a shared library / dynamic shared object file / similar
     foreign container specified by designated `pathname', such as a
     .so on an `elf' platform.

     Locating the shared object follows standard rules of the platform,
     consult the manual page for dlopen(3) for details. Typically paths
     speficied by environment variables such as LD_LIBRARY_PATH are
     searched if the `pathname' has no directory, but on some systems
     (eg. Mac `os' X) search may happen even if `pathname' is absolute.
     (On Windows LoadLibrary is used instead of dlopen(3).)

     On non-Windows platoforms calling `load-shared-object' again with
     an `pathname' `equal' to the designated pathname of a previous
     call will replace the old definitions; if a symbol was previously
     referenced thru the object and is not present in the reloaded
     version an error will be signalled. Reloading may not work as
     expected if user or library-code has called dlopen(3) on the same
     shared object.

     `load-shared-object' interacts with `sb-ext:save-lisp-and-die:'

     1. If `dont-save' is true (default is NIL), the shared object will
     be dropped when `save-lisp-and-die' is called `--' otherwise
     shared objects are reloaded automatically when a saved core starts
     up. Specifying `dont-save' can be useful when the location of the
     shared object on startup is uncertain.

     2. On most platforms references in compiled code to foreign
     symbols in shared objects (such as those generated by
     DEFINE-ALIEN-ROUTINE) remain valid across `save-lisp-and-die'. On
     those platforms where this is not supported, a `warning' will be
     signalled when the core is saved `--' this is orthogonal from
     `dont-save'.


File: sbcl.info,  Node: Foreign Function Calls,  Next: Step-By-Step Example of the Foreign Function Interface,  Prev: Loading Shared Object Files,  Up: Foreign Function Interface

8.7 Foreign Function Calls
==========================

The foreign function call interface allows a Lisp program to call many
functions written in languages that use the C calling convention.

   Lisp sets up various signal handling routines and other environment
information when it first starts up, and expects these to be in place
at all times. The C functions called by Lisp should not change the
environment, especially the signal handlers: the signal handlers
installed by Lisp typically have interesting flags set (e.g to request
machine context information, or for signal delivery on an alternate
stack) which the Lisp runtime relies on for correct operation.  Precise
details of how this works may change without notice between versions;
the source, or the brain of a friendly SBCL developer, is the only
documentation.  Users of a Lisp built with the `:sb-thread' feature
should also read the section about threads, *Note Threading::.

* Menu:

* The alien-funcall Primitive::
* The define-alien-routine Macro::
* define-alien-routine Example::
* Calling Lisp From C::


File: sbcl.info,  Node: The alien-funcall Primitive,  Next: The define-alien-routine Macro,  Up: Foreign Function Calls

8.7.1 The `alien-funcall' Primitive
-----------------------------------

 -- Function: sb-alien:alien-funcall ALIEN-FUNCTION &rest ARGUMENTS
     The `alien-funcall' function is the foreign function call
     primitive: ALIEN-FUNCTION is called with the supplied ARGUMENTS
     and its C return value is returned as a Lisp value.  The
     ALIEN-FUNCTION is an arbitrary run-time expression; to refer to a
     constant function, use `extern-alien' or a value defined by
     `define-alien-routine'.

     The type of `alien-function' must be `(alien (function ...))'  or
     `(alien (* (function ...)))'.  The function type is used to
     determine how to call the function (as though it was declared with
     a prototype.)  The type need not be known at compile time, but
     only known-type calls are efficiently compiled.  Limitations:

        * Structure type return values are not implemented.

        * Passing of structures by value is not implemented.



   Here is an example which allocates a `(struct foo)', calls a foreign
function to initialize it, then returns a Lisp vector of all the `(*
(struct foo))' objects filled in by the foreign call:

     ;; Allocate a foo on the stack.
     (with-alien ((f (struct foo)))
       ;; Call some C function to fill in foo fields.
       (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
                      (addr f))
       ;; Find how many foos to use by getting the A field.
       (let* ((num (slot f 'a))
              (result (make-array num)))
         ;; Get a pointer to the array so that we don't have to keep extracting it:
         (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
           ;; Loop over the first N elements and stash them in the result vector.
           (dotimes (i num)
             (setf (svref result i) (deref (deref a) i)))
           ;; Voila.
           result)))


File: sbcl.info,  Node: The define-alien-routine Macro,  Next: define-alien-routine Example,  Prev: The alien-funcall Primitive,  Up: Foreign Function Calls

8.7.2 The `define-alien-routine' Macro
--------------------------------------

 -- Macro: sb-alien:define-alien-routine NAME RESULT-TYPE &rest
          ARG-SPECIFIERS
     The `define-alien-routine' macro is a convenience for
     automatically generating Lisp interfaces to simple foreign
     functions.  The primary feature is the parameter style
     specification, which translates the C pass-by-reference idiom into
     additional return values.

     NAME is usually a string external symbol, but may also be a symbol
     Lisp name or a list of the foreign name and the Lisp name.  If
     only one name is specified, the other is automatically derived as
     for `extern-alien'.  RESULT-TYPE is the alien type of the return
     value.

     Each element of the ARG-SPECIFIERS list specifies an argument to
     the foreign function, and is of the form
          (aname atype &amp;optional style)

     ANAME is the symbol name of the argument to the constructed
     function (for documentation). ATYPE is the alien type of
     corresponding foreign argument.  The semantics of the actual call
     are the same as for `alien-funcall'. STYLE specifies how this
     argument should be handled at call and return time, and should be
     one of the following:

        * `:in' specifies that the argument is passed by value. This is
          the default. `:in' arguments have no corresponding return
          value from the Lisp function.

        * `:copy' is similar to `:in', but the argument is copied to a
          pre-allocated object and a pointer to this object is passed
          to the foreign routine.

        * `:out' specifies a pass-by-reference output value.  The type
          of the argument must be a pointer to a fixed-sized object
          (such as an integer or pointer).  `:out' and `:in-out' style
          cannot be used with pointers to arrays, records or functions.
          An object of the correct size is allocated on the stack, and
          its address is passed to the foreign function.  When the
          function returns, the contents of this location are returned
          as one of the values of the Lisp function (and the location
          is automatically deallocated).

        * `:in-out' is a combination of `:copy' and `:out'.  The
          argument is copied to a pre-allocated object and a pointer to
          this object is passed to the foreign routine.  On return, the
          contents of this location is returned as an additional value.


          Note: Any efficiency-critical foreign interface function
          should be inline expanded, which can be done by preceding the
          `define-alien-routine' call with:

               (declaim (inline lisp-name))

          In addition to avoiding the Lisp call overhead, this allows
          pointers, word-integers and floats to be passed using
          non-descriptor representations, avoiding consing.)



File: sbcl.info,  Node: define-alien-routine Example,  Next: Calling Lisp From C,  Prev: The define-alien-routine Macro,  Up: Foreign Function Calls

8.7.3 `define-alien-routine' Example
------------------------------------

Consider the C function `cfoo' with the following calling convention:

     void
     cfoo (str, a, i)
         char *str;
         char *a; /* update */
         int *i; /* out */
     {
       /* body of cfoo(...) */
     }

   This can be described by the following call to
`define-alien-routine':

     (define-alien-routine "cfoo" void
       (str c-string)
       (a char :in-out)
       (i int :out))

   The Lisp function `cfoo' will have two arguments (STR and A) and two
return values (A and I).


File: sbcl.info,  Node: Calling Lisp From C,  Prev: define-alien-routine Example,  Up: Foreign Function Calls

8.7.4 Calling Lisp From C
-------------------------

Calling Lisp functions from C is sometimes possible, but is extremely
hackish and poorly supported as of SBCL 0.7.5.  See `funcall0' ...
`funcall3' in the runtime system. The arguments must be valid SBCL
object descriptors (so that e.g. fixnums must be left-shifted by 2.) As
of SBCL 0.7.5, the format of object descriptors is documented only by
the source code and, in parts, by the old CMUCL `INTERNALS'
documentation.

   Note that the garbage collector moves objects, and won't be able to
fix up any references in C variables.  There are three mechanisms for
coping with this:

  1. The `sb-ext:purify' moves all live Lisp data into static or
     read-only areas such that it will never be moved (or freed) again
     in the life of the Lisp session

  2. `sb-sys:with-pinned-objects' is a macro which arranges for some
     set of objects to be pinned in memory for the dynamic extent of its
     body forms.  On ports which use the generational garbage collector
     (as of SBCL 0.8.3, only the x86) this has a page granularity -
     i.e. the entire 4k page or pages containing the objects will be
     locked down. On other ports it is implemented by turning off GC
     for the duration (so could be said to have a whole-world
     granularity).

  3. Disable GC, using the `without-gcing' macro.


File: sbcl.info,  Node: Step-By-Step Example of the Foreign Function Interface,  Prev: Foreign Function Calls,  Up: Foreign Function Interface

8.8 Step-By-Step Example of the Foreign Function Interface
==========================================================

This section presents a complete example of an interface to a somewhat
complicated C function.

   Suppose you have the following C function which you want to be able
to call from Lisp in the file `test.c'

     struct c_struct
     {
       int x;
       char *s;
     };

     struct c_struct *c_function (i, s, r, a)
         int i;
         char *s;
         struct c_struct *r;
         int a[10];
     {
       int j;
       struct c_struct *r2;

       printf("i = %d\n", i);
       printf("s = %s\n", s);
       printf("r->x = %d\n", r->x);
       printf("r->s = %s\n", r->s);
       for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
       r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
       r2->x = i + 5;
       r2->s = "a C string";
       return(r2);
     };

   It is possible to call this C function from Lisp using the file
`test.lisp' containing

     (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
     (cl:in-package "TEST-C-CALL")

     ;;; Define the record C-STRUCT in Lisp.
     (define-alien-type nil
         (struct c-struct
                 (x int)
                 (s c-string)))

     ;;; Define the Lisp function interface to the C routine.  It returns a
     ;;; pointer to a record of type C-STRUCT.  It accepts four parameters:
     ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
     ;;; record; and A, a pointer to the array of 10 ints.
     ;;;
     ;;; The INLINE declaration eliminates some efficiency notes about heap
     ;;; allocation of alien values.
     (declaim (inline c-function))
     (define-alien-routine c-function
         (* (struct c-struct))
       (i int)
       (s c-string)
       (r (* (struct c-struct)))
       (a (array int 10)))

     ;;; a function which sets up the parameters to the C function and
     ;;; actually calls it
     (defun call-cfun ()
       (with-alien ((ar (array int 10))
                    (c-struct (struct c-struct)))
         (dotimes (i 10)                     ; Fill array.
           (setf (deref ar i) i))
         (setf (slot c-struct 'x) 20)
         (setf (slot c-struct 's) "a Lisp string")

         (with-alien ((res (* (struct c-struct))
                           (c-function 5 "another Lisp string" (addr c-struct) ar)))
           (format t "~&amp;back from C function~%")
           (multiple-value-prog1
               (values (slot res 'x)
                       (slot res 's))

             ;; Deallocate result. (after we are done referring to it:
             ;; "Pillage, *then* burn.")
             (free-alien res)))))

   To execute the above example, it is necessary to compile the C
routine, e.g.: `cc -c test.c && ld -shared -o test.so test.o' (In order
to enable incremental loading with some linkers, you may need to say
`cc -G 0 -c test.c')

   Once the C code has been compiled, you can start up Lisp and load it
in: `sbcl'.  Lisp should start up with its normal prompt.

   Within Lisp, compile the Lisp file. (This step can be done
separately. You don't have to recompile every time.)  `(compile-file
"test.lisp")'

   Within Lisp, load the foreign object file to define the necessary
symbols: `(load-shared-object "test.so")'.

   Now you can load the compiled Lisp ("fasl") file into Lisp: `(load
"test.fasl")' And once the Lisp file is loaded, you can call the Lisp
routine that sets up the parameters and calls the C function:
`(test-c-call::call-cfun)'

   The C routine should print the following information to standard
output:

     i = 5
     s = another Lisp string
     r->x = 20
     r->s = a Lisp string
     a[0] = 0.
     a[1] = 1.
     a[2] = 2.
     a[3] = 3.
     a[4] = 4.
     a[5] = 5.
     a[6] = 6.
     a[7] = 7.
     a[8] = 8.
     a[9] = 9.

   After return from the C function, the Lisp wrapper function should
print the following output:

     back from C function

   And upon return from the Lisp wrapper function, before the next
prompt is printed, the Lisp read-eval-print loop should print the
following return values:

     10
     "a C string"


File: sbcl.info,  Node: Pathnames,  Next: Extensible Streams,  Prev: Foreign Function Interface,  Up: Top

9 Pathnames
***********

* Menu:

* Lisp Pathnames::
* Native Filenames::


File: sbcl.info,  Node: Lisp Pathnames,  Next: Native Filenames,  Up: Pathnames

9.1 Lisp Pathnames
==================

There are many aspects of ANSI Common Lisp's pathname support which are
implementation-defined and so need documentation.

9.1.1 The SYS Logical Pathname Host
-----------------------------------

The logical pathname host named by `"SYS"' exists in SBCL.  Its
`logical-pathname-translations' may be set by the site or the user
applicable to point to the locations of the system's sources; in
particular, the core system's source files match the logical pathname
`"SYS:SRC;**;*.*.*"', and the contributed modules' source files match
`"SYS:CONTRIB;**;*.*.*"'.


File: sbcl.info,  Node: Native Filenames,  Prev: Lisp Pathnames,  Up: Pathnames

9.2 Native Filenames
====================

In some circumstances, what is wanted is a Lisp pathname object which
corresponds to a string produced by the Operating System.  In this case,
some of the default parsing rules are inappropriate: most filesystems do
not have a native understanding of wild pathnames; such functionality is
often provided by shells above the OS, often in mutually-incompatible
ways.

   To allow the user to deal with this, the following functions are
provided: `parse-native-namestring' and `native-pathname' return the
closest equivalent Lisp pathname to a given string (appropriate for the
Operating System), while `native-namestring' converts a non-wild
pathname designator to the equivalent native namestring, if possible.
Some Lisp pathname concepts (such as the `:back' directory component)
have no direct equivalents in most Operating Systems; the behaviour of
`native-namestring' is unspecified if an inappropriate pathname
designator is passed to it.  Additionally, note that conversion from
pathname to native filename and back to pathname should not be expected
to preserve equivalence under `equal'.

 -- Function: sb-ext:parse-native-namestring thing &optional host
          defaults &key start end junk-allowed as-directory
     Convert `thing' into a pathname, using the native conventions
     appropriate for the pathname host `host', or if not specified the
     host of `defaults'.  If `thing' is a string, the parse is bounded
     by `start' and `end', and error behaviour is controlled by
     `junk-allowed', as with `parse-namestring'.  For file systems
     whose native conventions allow directories to be indicated as
     files, if `as-directory' is true, return a pathname denoting
     `thing' as a directory.

 -- Function: sb-ext:native-pathname pathspec
     Convert `pathspec' (a pathname designator) into a pathname,
     assuming the operating system native pathname conventions.

 -- Function: sb-ext:native-namestring pathname &key as-file
     Construct the full native (name)string form of `pathname'.  For
     file systems whose native conventions allow directories to be
     indicated as files, if `as-file' is true and the name, type, and
     version components of `pathname' are all `nil' or `:unspecific',
     construct a string that names the directory according to the file
     system's syntax for files.

   Because some file systems permit the names of directories to be
expressed in multiple ways, it is occasionally necessary to parse a
native file name "as a directory name" or to produce a native file name
that names a directory "as a file".  For these cases,
`parse-native-namestring' accepts the keyword argument `as-directory'
to force a filename to parse as a directory, and `native-namestring'
accepts the keyword argument `as-file' to force a pathname to unparse
as a file.  For example,

     ; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
     ; Under the default rules for native filenames, these parse and
     ; unparse differently.
     (defvar *p*)
     (setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
     (pathname-name *p*) => NIL
     (pathname-directory *p*) => (:ABSOLUTE "tmp")
     (native-namestring *p*) => "/tmp/"

     (setf *p* (parse-native-namestring "/tmp")) => #P"/tmp"
     (pathname-name *p*) => "tmp"
     (pathname-directory *p*) => (:ABSOLUTE)
     (native-namestring *p*) => "/tmp"

     ; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
     ; both the second string to parse the way the first does.
     (setf *p* (parse-native-namestring "/tmp"
                                        nil *default-pathname-defaults*
                                        :as-directory t)) => #P"/tmp/"
     (pathname-name *p*) => NIL
     (pathname-directory *p*) => (:ABSOLUTE "tmp")

     ; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
     ; parsed from the first string to unparse as the second string.
     (setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
     (native-namestring *p* :as-file t) => "/tmp"


File: sbcl.info,  Node: Extensible Streams,  Next: Package Locks,  Prev: Pathnames,  Up: Top

10 Extensible Streams
*********************

SBCL supports various extensions of ANSI Common Lisp streams.

*Bivalent Streams*
     A type of stream that can read and write both `character' and
     `(unsigned-byte 8)' values.

*Gray Streams*
     User-overloadable CLOS classes whose instances can be used as Lisp
     streams (e.g. passed as the first argument to `format').

*Simple Streams*
     The bundled contrib module "sb-simple-streams" implements a subset
     of the Franz Allegro simple-streams proposal.


* Menu:

* Bivalent Streams::
* Gray Streams::
* Simple Streams::


File: sbcl.info,  Node: Bivalent Streams,  Next: Gray Streams,  Up: Extensible Streams

10.1 Bivalent Streams
=====================

A "bivalent stream" can be used to read and write both `character' and
`(unsigned-byte 8)' values.  A bivalent stream is created by calling
`open' with the argument `:element-type :default'.  On such a stream,
both binary and character data can be read and written with the usual
input and output functions.

     Streams are _not_ created bivalent by default for performance
     reasons.  Bivalent streams are incompatible with `fast-read-char',
     an internal optimization in sbcl's stream machinery that
     bulk-converts octets to characters and implements a fast path
     through `read-char'.


File: sbcl.info,  Node: Gray Streams,  Next: Simple Streams,  Prev: Bivalent Streams,  Up: Extensible Streams

10.2 Gray Streams
=================

The Gray Streams interface is a widely supported extension that
provides for definition of CLOS-extensible stream classes.  Gray stream
classes are implemented by adding methods to generic functions
analogous to Common Lisp's standard I/O functions.  Instances of Gray
stream classes may be used with any I/O operation where a non-Gray
stream can, provided that all required methods have been implemented
suitably.

* Menu:

* Gray Streams classes::
* Methods common to all streams::
* Input stream methods::
* Output stream methods::
* Binary stream methods::
* Character input stream methods::
* Character output stream methods::
* Gray Streams examples::


File: sbcl.info,  Node: Gray Streams classes,  Next: Methods common to all streams,  Up: Gray Streams

10.2.1 Gray Streams classes
---------------------------

The defined Gray Stream classes are these:

 -- Class: sb-gray:fundamental-stream
     Class precedence list: `fundamental-stream, standard-object,
     stream, t'

     the base class for all Gray streams

 -- Class: sb-gray:fundamental-input-stream
     Class precedence list: `fundamental-input-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray input streams

The function input-stream-p will return true of any generalized
instance of fundamental-input-stream.

 -- Class: sb-gray:fundamental-output-stream
     Class precedence list: `fundamental-output-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray output streams

The function output-stream-p will return true of any generalized
instance of fundamental-output-stream.

 -- Class: sb-gray:fundamental-binary-stream
     Class precedence list: `fundamental-binary-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray streams whose element-type is a subtype
     of unsigned-byte or signed-byte

Note that instantiable subclasses of fundamental-binary-stream should
provide (or inherit) an applicable method for the generic function
stream-element-type.

 -- Class: sb-gray:fundamental-character-stream
     Class precedence list: `fundamental-character-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray streams whose element-type is a subtype
     of character

 -- Class: sb-gray:fundamental-binary-input-stream
     Class precedence list: `fundamental-binary-input-stream,
     fundamental-input-stream, fundamental-binary-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray input streams whose element-type is a
     subtype of unsigned-byte or signed-byte

 -- Class: sb-gray:fundamental-binary-output-stream
     Class precedence list: `fundamental-binary-output-stream,
     fundamental-output-stream, fundamental-binary-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray output streams whose element-type is a
     subtype of unsigned-byte or signed-byte

 -- Class: sb-gray:fundamental-character-input-stream
     Class precedence list: `fundamental-character-input-stream,
     fundamental-input-stream, fundamental-character-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray input streams whose element-type is a
     subtype of character

 -- Class: sb-gray:fundamental-character-output-stream
     Class precedence list: `fundamental-character-output-stream,
     fundamental-output-stream, fundamental-character-stream,
     fundamental-stream, standard-object, stream, t'

     a superclass of all Gray output streams whose element-type is a
     subtype of character


File: sbcl.info,  Node: Methods common to all streams,  Next: Input stream methods,  Prev: Gray Streams classes,  Up: Gray Streams

10.2.2 Methods common to all streams
------------------------------------

These generic functions can be specialized on any generalized instance
of fundamental-stream.

 -- Generic Function: cl:stream-element-type stream
     Return a type specifier for the kind of object returned by the
     `stream'. The class `fundamental-character-stream' provides a
     default method   which returns `character'.

 -- Generic Function: cl:close stream &key abort
     Close the given `stream'. No more I/O may be performed, but
     inquiries may still be made. If `:abort' is true, an attempt is
     made   to clean up the side effects of having created the stream.

 -- Generic Function: sb-gray:stream-file-position stream &optional
          position-spec
     Used by `file-position'. Returns or changes the current position
     within `stream'.


File: sbcl.info,  Node: Input stream methods,  Next: Output stream methods,  Prev: Methods common to all streams,  Up: Gray Streams

10.2.3 Input stream methods
---------------------------

These generic functions may be specialized on any generalized instance
of fundamental-input-stream.

 -- Generic Function: sb-gray:stream-clear-input stream
     This is like `cl:clear-input', but for Gray streams, returning
     `nil'.    The default method does nothing.

 -- Generic Function: sb-gray:stream-read-sequence stream seq &optional
          start end
     This is like `cl:read-sequence', but for Gray streams.


File: sbcl.info,  Node: Character input stream methods,  Next: Character output stream methods,  Prev: Binary stream methods,  Up: Gray Streams

10.2.4 Character input stream methods
-------------------------------------

These generic functions are used to implement subclasses of
fundamental-input-stream:

 -- Generic Function: sb-gray:stream-peek-char stream
     This is used to implement `peek-char'; this corresponds to
     `peek-type' of `nil'.    It returns either a character or `:eof'.
     The default method calls   `stream-read-char' and
     `stream-unread-char'.

 -- Generic Function: sb-gray:stream-read-char-no-hang stream
     This is used to implement `read-char-no-hang'. It returns either a
      character, or `nil' if no input is currently available, or
     `:eof' if   end-of-file is reached. The default method provided by
      `fundamental-character-input-stream' simply calls
     `stream-read-char'; this   is sufficient for file streams, but
     interactive streams should define   their own method.

 -- Generic Function: sb-gray:stream-read-char stream
     Read one character from the stream. Return either a   character
     object, or the symbol `:eof' if the stream is at end-of-file.
     Every subclass of `fundamental-character-input-stream' must define
     a   method for this function.

 -- Generic Function: sb-gray:stream-read-line stream
     This is used by `read-line'. A string is returned as the first
     value. The   second value is true if the string was terminated by
     end-of-file   instead of the end of a line. The default method
     uses repeated   calls to `stream-read-char'.

 -- Generic Function: sb-gray:stream-listen stream
     This is used by `listen'. It returns true or false. The default
     method uses   `stream-read-char-no-hang' and `stream-unread-char'.
     Most streams should   define their own method since it will
     usually be trivial and will   always be more efficient than the
     default method.

 -- Generic Function: sb-gray:stream-unread-char stream character
     Un-do the last call to `stream-read-char', as in `unread-char'.
     Return `nil'. Every subclass of
     `fundamental-character-input-stream'   must define a method for
     this function.


File: sbcl.info,  Node: Output stream methods,  Next: Binary stream methods,  Prev: Input stream methods,  Up: Gray Streams

10.2.5 Output stream methods
----------------------------

These generic functions are used to implement subclasses of
fundamental-output-stream:

 -- Generic Function: sb-gray:stream-clear-output stream
     This is like `cl:clear-output', but for Gray streams: clear the
     given   output `stream'. The default method does nothing.

 -- Generic Function: sb-gray:stream-finish-output stream
     Attempts to ensure that all output sent to the Stream has reached
     its destination, and only then returns false. Implements
     `finish-output'. The default method does nothing.

 -- Generic Function: sb-gray:stream-force-output stream
     Attempts to force any buffered output to be sent. Implements
     `force-output'. The default method does nothing.

 -- Generic Function: sb-gray:stream-write-sequence stream seq
          &optional start end
     This is like `cl:write-sequence', but for Gray streams.


File: sbcl.info,  Node: Binary stream methods,  Next: Character input stream methods,  Prev: Output stream methods,  Up: Gray Streams

10.2.6 Binary stream methods
----------------------------

The following generic functions are available for subclasses of
fundamental-binary-stream:

 -- Generic Function: sb-gray:stream-read-byte stream
     Used by `read-byte'; returns either an integer, or the symbol
     `:eof'   if the stream is at end-of-file.

 -- Generic Function: sb-gray:stream-write-byte stream integer
     Implements `write-byte'; writes the integer to the stream and
     returns the integer as the result.


File: sbcl.info,  Node: Character output stream methods,  Next: Gray Streams examples,  Prev: Character input stream methods,  Up: Gray Streams

10.2.7 Character output stream methods
--------------------------------------

These generic functions are used to implement subclasses of
fundamental-character-output-stream:

 -- Generic Function: sb-gray:stream-advance-to-column stream column
     Write enough blank space so that the next character will be
     written at the specified column. Returns true if the operation is
     successful, or `nil' if it is not supported for this stream. This
     is   intended for use by by `pprint' and `format' ~T. The default
     method uses   `stream-line-column' and repeated calls to
     `stream-write-char' with a   `#space' character; it returns `nil'
     if `stream-line-column' returns `nil'.

 -- Generic Function: sb-gray:stream-fresh-line stream
     Outputs a new line to the Stream if it is not positioned at the
     begining of a line. Returns `t' if it output a new line, nil
     otherwise. Used by `fresh-line'. The default method uses
     `stream-start-line-p' and `stream-terpri'.

 -- Generic Function: sb-gray:stream-line-column stream
     Return the column number where the next character   will be
     written, or `nil' if that is not meaningful for this stream.
     The first column on a line is numbered 0. This function is used in
      the implementation of `pprint' and the `format' ~T directive.
     For every   character output stream class that is defined, a
     method must be   defined for this function, although it is
     permissible for it to   always return `nil'.

 -- Generic Function: sb-gray:stream-line-length stream
     Return the stream line length or `nil'.

 -- Generic Function: sb-gray:stream-start-line-p stream
     Is `stream' known to be positioned at the beginning of a line?
     It is permissible for an implementation to always return   `nil'.
     This is used in the implementation of `fresh-line'. Note that
     while a value of 0 from `stream-line-column' also indicates the
     beginning of a line, there are cases where `stream-start-line-p'
     can be   meaningfully implemented although `stream-line-column'
     can't be. For   example, for a window using variable-width
     characters, the column   number isn't very meaningful, but the
     beginning of the line does have   a clear meaning. The default
     method for `stream-start-line-p' on class
     `fundamental-character-output-stream' uses `stream-line-column',
     so if   that is defined to return `nil', then a method should be
     provided for   either `stream-start-line-p' or `stream-fresh-line'.

 -- Generic Function: sb-gray:stream-terpri stream
     Writes an end of line, as for `terpri'. Returns `nil'. The default
      method does (STREAM-WRITE-CHAR stream #NEWLINE).

 -- Generic Function: sb-gray:stream-write-char stream character
     Write `character' to `stream' and return `character'. Every
     subclass of `fundamental-character-output-stream' must have a
     method   defined for this function.

 -- Generic Function: sb-gray:stream-write-string stream string
          &optional start end
     This is used by `write-string'. It writes the string to the stream,
      optionally delimited by start and end, which default to 0 and
     `nil'.    The string argument is returned. The default method
     provided by   `fundamental-character-output-stream' uses repeated
     calls to   `stream-write-char'.


File: sbcl.info,  Node: Gray Streams examples,  Prev: Character output stream methods,  Up: Gray Streams

10.2.8 Gray Streams examples
----------------------------

Below are two classes of stream that can be conveniently defined as
wrappers for Common Lisp streams.  These are meant to serve as examples
of minimal implementations of the protocols that must be followed when
defining Gray streams.  Realistic uses of the Gray Streams API would
implement the various methods that can do I/O in batches, such as
`stream-read-line', `stream-write-string', `stream-read-sequence', and
`stream-write-sequence'.

* Menu:

* Character counting input stream::
* Output prefixing character stream::


File: sbcl.info,  Node: Character counting input stream,  Next: Output prefixing character stream,  Up: Gray Streams examples

10.2.8.1 Character counting input stream
........................................

It is occasionally handy for programs that process input files to count
the number of characters and lines seen so far, and the number of
characters seen on the current line, so that useful messages may be
reported in case of parsing errors, etc.  Here is a character input
stream class that keeps track of these counts.  Note that all character
input streams must implement `stream-read-char' and
`stream-unread-char'.

     (defclass wrapped-stream (fundamental-stream)
       ((stream :initarg :stream :reader stream-of)))

     (defmethod stream-element-type ((stream wrapped-stream))
       (stream-element-type (stream-of stream)))

     (defmethod close ((stream wrapped-stream) &key abort)
       (close (stream-of stream) :abort abort))

     (defclass wrapped-character-input-stream
         (wrapped-stream fundamental-character-input-stream)
       ())

     (defmethod stream-read-char ((stream wrapped-character-input-stream))
       (read-char (stream-of stream) nil :eof))

     (defmethod stream-unread-char ((stream wrapped-character-input-stream)
                                    char)
       (unread-char char (stream-of stream)))

     (defclass counting-character-input-stream
         (wrapped-character-input-stream)
       ((char-count :initform 1 :accessor char-count-of)
        (line-count :initform 1 :accessor line-count-of)
        (col-count :initform 1 :accessor col-count-of)
        (prev-col-count :initform 1 :accessor prev-col-count-of)))

     (defmethod stream-read-char ((stream counting-character-input-stream))
       (with-accessors ((inner-stream stream-of) (chars char-count-of)
                        (lines line-count-of) (cols col-count-of)
                        (prev prev-col-count-of)) stream
           (let ((char (call-next-method)))
             (cond ((eql char :eof)
                    :eof)
                   ((char= char #\Newline)
                    (incf lines)
                    (incf chars)
                    (setf prev cols)
                    (setf cols 1)
                    char)
                   (t
                    (incf chars)
                    (incf cols)
                    char)))))

     (defmethod stream-unread-char ((stream counting-character-input-stream)
                                    char)
       (with-accessors ((inner-stream stream-of) (chars char-count-of)
                        (lines line-count-of) (cols col-count-of)
                        (prev prev-col-count-of)) stream
           (cond ((char= char #\Newline)
                  (decf lines)
                  (decf chars)
                  (setf cols prev))
                 (t
                  (decf chars)
                  (decf cols)
                  char))
           (call-next-method)))

   The default methods for `stream-read-char-no-hang',
`stream-peek-char', `stream-listen', `stream-clear-input',
`stream-read-line', and `stream-read-sequence' should be sufficient
(though the last two will probably be slower than methods that
forwarded directly).

   Here's a sample use of this class:

     (with-input-from-string (input "1 2
      3 :foo  ")
       (let ((counted-stream (make-instance 'counting-character-input-stream
                              :stream input)))
         (loop for thing = (read counted-stream) while thing
            unless (numberp thing) do
              (error "Non-number ~S (line ~D, column ~D)" thing
                     (line-count-of counted-stream)
                     (- (col-count-of counted-stream)
                        (length (format nil "~S" thing))))
            end
            do (print thing))))

     1
     2
     3
     Non-number :FOO (line 2, column 5)
       [Condition of type SIMPLE-ERROR]


File: sbcl.info,  Node: Output prefixing character stream,  Prev: Character counting input stream,  Up: Gray Streams examples

10.2.8.2 Output prefixing character stream
..........................................

One use for a wrapped output stream might be to prefix each line of
text with a timestamp, e.g., for a logging stream.  Here's a simple
stream that does this, though without any fancy line-wrapping.  Note
that all character output stream classes must implement
`stream-write-char' and `stream-line-column'.

     (defclass wrapped-stream (fundamental-stream)
       ((stream :initarg :stream :reader stream-of)))

     (defmethod stream-element-type ((stream wrapped-stream))
       (stream-element-type (stream-of stream)))

     (defmethod close ((stream wrapped-stream) &key abort)
       (close (stream-of stream) :abort abort))

     (defclass wrapped-character-output-stream
         (wrapped-stream fundamental-character-output-stream)
       ((col-index :initform 0 :accessor col-index-of)))

     (defmethod stream-line-column ((stream wrapped-character-output-stream))
       (col-index-of stream))

     (defmethod stream-write-char ((stream wrapped-character-output-stream)
                                   char)
       (with-accessors ((inner-stream stream-of) (cols col-index-of)) stream
         (write-char char inner-stream)
         (if (char= char #\Newline)
             (setf cols 0)
             (incf cols))))

     (defclass prefixed-character-output-stream
         (wrapped-character-output-stream)
       ((prefix :initarg :prefix :reader prefix-of)))

     (defgeneric write-prefix (prefix stream)
       (:method ((prefix string) stream) (write-string prefix stream))
       (:method ((prefix function) stream) (funcall prefix stream)))

     (defmethod stream-write-char ((stream prefixed-character-output-stream)
                                   char)
       (with-accessors ((inner-stream stream-of) (cols col-index-of)
                        (prefix prefix-of)) stream
         (when (zerop cols)
           (write-prefix prefix inner-stream))
         (call-next-method)))

   As with the example input stream, this implements only the minimal
protocol.  A production implementation should also provide methods for
at least `stream-write-line', `stream-write-sequence'.

   And here's a sample use of this class:

     (flet ((format-timestamp (stream)
              (apply #'format stream "[~2@*~2,' D:~1@*~2,'0D:~0@*~2,'0D] "
                     (multiple-value-list (get-decoded-time)))))
       (let ((output (make-instance 'prefixed-character-output-stream
                                    :stream *standard-output*
                                    :prefix #'format-timestamp)))
         (loop for string in '("abc" "def" "ghi") do
              (write-line string output)
              (sleep 1))))

     [ 0:30:05] abc
     [ 0:30:06] def
     [ 0:30:07] ghi
     NIL


File: sbcl.info,  Node: Simple Streams,  Prev: Gray Streams,  Up: Extensible Streams

10.3 Simple Streams
===================

Simple streams are an extensible streams protocol that avoids some
problems with Gray streams.

   Documentation about simple streams is available at:

   `http://www.franz.com/support/documentation/6.2/doc/streams.htm'

   The implementation should be considered Alpha-quality; the basic
framework is there, but many classes are just stubs at the moment.

   See `SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP' for
things that should work.

   Known differences to the ACL behaviour:

   * `open' not return a simple-stream by default. This can be
     adjusted; see default-open-class in the file cl.lisp

   * `write-vector' is unimplemented.



File: sbcl.info,  Node: Package Locks,  Next: Threading,  Prev: Extensible Streams,  Up: Top

11 Package Locks
****************

None of the following sections apply to SBCL built without package
locking support.

   The interface described here is experimental: incompatible changes in
future SBCL releases are possible, even expected: the concept of
"implementation packages" and the associated operators may be renamed;
more operations (such as naming restarts or catch tags) may be added to
the list of operations violating package locks.

* Menu:

* Package Lock Concepts::
* Package Lock Dictionary::


File: sbcl.info,  Node: Package Lock Concepts,  Next: Package Lock Dictionary,  Up: Package Locks

11.1 Package Lock Concepts
==========================

* Menu:

* Package Lock Overview::
* Implementation Packages::
* Package Lock Violations::
* Package Locks in Compiled Code::
* Operations Violating Package Locks::


File: sbcl.info,  Node: Package Lock Overview,  Next: Implementation Packages,  Up: Package Lock Concepts

11.1.1 Package Locking Overview
-------------------------------

Package locks protect against unintentional modifications of a package:
they provide similar protection to user packages as is mandated to
`common-lisp' package by the ANSI specification. They are not, and
should not be used as, a security measure.

   Newly created packages are by default unlocked (see the `:lock'
option to `defpackage').

   The package `common-lisp' and SBCL internal implementation packages
are locked by default, including `sb-ext'.

   It may be beneficial to lock `common-lisp-user' as well, to ensure
that various libraries don't pollute it without asking, but this is not
currently done by default.


File: sbcl.info,  Node: Implementation Packages,  Next: Package Lock Violations,  Prev: Package Lock Overview,  Up: Package Lock Concepts

11.1.2 Implementation Packages
------------------------------

Each package has a list of associated implementation packages. A locked
package, and the symbols whose home package it is, can be modified
without violating package locks only when `*package*' is bound to one
of the implementation packages of the locked package.

   Unless explicitly altered by `defpackage',
`sb-ext:add-implementation-package', or
`sb-ext:remove-implementation-package' each package is its own (only)
implementation package.


File: sbcl.info,  Node: Package Lock Violations,  Next: Package Locks in Compiled Code,  Prev: Implementation Packages,  Up: Package Lock Concepts

11.1.3 Package Lock Violations
------------------------------

11.1.3.1 Lexical Bindings and Declarations
..........................................

Lexical bindings or declarations that violate package locks cause
result in a `program-error' being signalled at when the form that
violates package locks would be executed.

   A complete listing of operators affect by this is: `let', `let*',
`flet', `labels', `macrolet', and `symbol-macrolet', `declare'.

   Package locks affecting both lexical bindings and declarations can be
disabled locally with `sb-ext:disable-package-locks' declaration, and
re-enabled with `sb-ext:enable-package-locks' declaration.

   Example:

     (in-package :locked)

     (defun foo () ...)

     (defmacro with-foo (&body body)
       `(locally (declare (disable-package-locks locked:foo))
          (flet ((foo () ...))
            (declare (enable-package-locks locked:foo)) ; re-enable for body
            ,@body)))

11.1.3.2 Other Operations
.........................

If an non-lexical operation violates a package lock, a continuable
error that is of a subtype of `sb-ext:package-lock-violation' (subtype
of `package-error') is signalled when the operation is attempted.

   Additional restarts may be established for continuable package lock
violations for interactive use.

   The actual type of the error depends on circumstances that caused the
violation: operations on packages signal errors of type
`sb-ext:package-locked-error', and operations on symbols signal errors
of type `sb-ext:symbol-package-locked-error'.


File: sbcl.info,  Node: Package Locks in Compiled Code,  Next: Operations Violating Package Locks,  Prev: Package Lock Violations,  Up: Package Lock Concepts

11.1.4 Package Locks in Compiled Code
-------------------------------------

11.1.4.1 Interned Symbols
.........................

If file-compiled code contains interned symbols, then loading that code
into an image without the said symbols will not cause a package lock
violation, even if the packages in question are locked.

11.1.4.2 Other Limitations on Compiled Code
...........................................

With the exception of interned symbols, behaviour is unspecified if
package locks affecting compiled code are not the same during loading
of the code or execution.

   Specifically, code compiled with packages unlocked may or may not
fail to signal package-lock-violations even if the packages are locked
at runtime, and code compiled with packages locked may or may not signal
spurious package-lock-violations at runtime even if the packages are
unlocked.

   In practice all this means that package-locks have a negligible
performance penalty in compiled code as long as they are not violated.


File: sbcl.info,  Node: Operations Violating Package Locks,  Prev: Package Locks in Compiled Code,  Up: Package Lock Concepts

11.1.5 Operations Violating Package Locks
-----------------------------------------

11.1.5.1 Operations on Packages
...............................

The following actions cause a package lock violation if the package
operated on is locked, and `*package*' is not an implementation package
of that package, and the action would cause a change in the state of
the package (so e.g. exporting already external symbols is never a
violation). Package lock violations caused by these operations signal
errors of type `sb-ext:package-locked-error'.

  1. Shadowing a symbol in a package.

  2. Importing a symbol to a package.

  3. Uninterning a symbol from a package.

  4. Exporting a symbol from a package.

  5. Unexporting a symbol from a package.

  6. Changing the packages used by a package.

  7. Renaming a package.

  8. Deleting a package.


11.1.5.2 Operations on Symbols
..............................

Following actions cause a package lock violation if the home package of
the symbol operated on is locked, and `*package*' is not an
implementation package of that package. Package lock violations caused
by these action signal errors of type
`sb-ext:symbol-package-locked-error'.

   These actions cause only one package lock violation per lexically
apparent violated package.

   Example:

     ;;; Packages FOO and BAR are locked.
     ;;;
     ;;; Two lexically apparent violated packages: exactly two
     ;;; package-locked-errors will be signalled.

     (defclass foo:point ()
       ((x :accessor bar:x)
        (y :accessor bar:y)))

  1. Binding or altering its value lexically or dynamically, or
     establishing it as a symbol-macro.

     Exceptions:

        - If the symbol is not defined as a constant, global
          symbol-macro or a global dynamic variable, it may be
          lexically bound or established as a local symbol macro.

        - If the symbol is defined as a global dynamic variable, it may
          be assigned or bound.


  2. Defining, undefining, or binding it, or its setf name as a
     function.

     Exceptions:

        - If the symbol is not defined as a function, macro, or special
          operator it and its setf name may be lexically bound as a
          function.


  3. Defining, undefining, or binding it as a macro or compiler macro.

     Exceptions:

        - If the symbol is not defined as a function, macro, or special
          operator it may be lexically bound as a macro.


  4. Defining it as a type specifier or structure.

  5. Defining it as a declaration with a declaration proclamation.

  6. Declaring or proclaiming it special.

  7. Declaring or proclaiming its type or ftype.

     Exceptions:

        - If the symbol may be lexically bound, the type of that
          binding may be declared.

        - If the symbol may be lexically bound as a function, the ftype
          of that binding may be declared.


  8. Defining a setf expander for it.

  9. Defining it as a method combination type.

 10. Using it as the class-name argument to setf of find-class.

 11. Defining it as a hash table test using
     `sb-ext:define-hash-table-test'.



File: sbcl.info,  Node: Package Lock Dictionary,  Prev: Package Lock Concepts,  Up: Package Locks

11.2 Package Lock Dictionary
============================

 -- Declaration: sb-ext:disable-package-locks
     Syntax: `(sb-ext:disable-package-locks symbol*)'

     Disables package locks affecting the named symbols during
     compilation in the lexical scope of the declaration. Disabling
     locks on symbols whose home package is unlocked, or disabling an
     already disabled lock, has no effect.

 -- Declaration: sb-ext:enable-package-locks
     Syntax: `(sb-ext:enable-package-locks symbol*)'

     Re-enables package locks affecting the named symbols during
     compilation in the lexical scope of the declaration. Enabling
     locks that were not first disabled with
     `sb-ext:disable-package-locks' declaration, or enabling locks that
     are already enabled has no effect.

 -- Condition: sb-ext:package-lock-violation
     Class precedence list: `package-lock-violation, package-error,
     error, serious-condition, condition, t'

     Subtype of `cl:package-error'. A subtype of this error is signalled
     when a package-lock is violated.

 -- Condition: sb-ext:package-locked-error
     Class precedence list: `package-locked-error,
     package-lock-violation, package-error, error, serious-condition,
     condition, t'

     Subtype of `sb-ext:package-lock-violation'. An error of this type
     is signalled when an operation on a package violates a package
     lock.

 -- Condition: sb-ext:symbol-package-locked-error
     Class precedence list: `symbol-package-locked-error,
     package-lock-violation, package-error, error, serious-condition,
     condition, t'

     Subtype of `sb-ext:package-lock-violation'. An error of this type
     is signalled when an operation on a symbol violates a package
     lock. The symbol that caused the violation is accessed by the
     function `sb-ext:package-locked-error-symbol'.

 -- Function: sb-ext:package-locked-error-symbol
          symbol-package-locked-error
     Returns the symbol that caused the `symbol-package-locked-error'
     condition.

 -- Function: sb-ext:package-locked-p package
     Returns `t' when `package' is locked, `nil' otherwise. Signals an
     error if `package' doesn't designate a valid package.

 -- Function: sb-ext:lock-package package
     Locks `package' and returns `t'. Has no effect if `package' was
     already locked. Signals an error if `package' is not a valid
     package designator

 -- Function: sb-ext:unlock-package package
     Unlocks `package' and returns `t'. Has no effect if `package' was
     already unlocked. Signals an error if `package' is not a valid
     package designator.

 -- Function: sb-ext:package-implemented-by-list package
     Returns a list containing the implementation packages of
     `package'. Signals an error if `package' is not a valid package
     designator.

 -- Function: sb-ext:package-implements-list package
     Returns the packages that `package' is an implementation package
     of. Signals an error if `package' is not a valid package
     designator.

 -- Function: sb-ext:add-implementation-package packages-to-add
          &optional package
     Adds `packages-to-add' as implementation packages of `package'.
     Signals an error if `package' or any of the `packages-to-add' is
     not a valid package designator.

 -- Function: sb-ext:remove-implementation-package packages-to-remove
          &optional package
     Removes `packages-to-remove' from the implementation packages of
     `package'. Signals an error if `package' or any of the
     `packages-to-remove' is not a valid package designator.

 -- Macro: sb-ext:without-package-locks &body body
     Ignores all runtime package lock violations during the execution of
     body. Body can begin with declarations.

 -- Macro: sb-ext:with-unlocked-packages (&rest packages) &body forms
     Unlocks `packages' for the dynamic scope of the body. Signals an
     error if any of `packages' is not a valid package designator.

 -- Macro: defpackage name [[option]]* => package
     Options are extended to include the following:

        * `:lock' BOOLEAN

          If the argument to `:lock' is `t', the package is initially
          locked.  If `:lock' is not provided it defaults to `nil'.

        * `:implement' PACKAGE-DESIGNATOR*

          The package is added as an implementation package to the
          packages named. If `:implement' is not provided, it defaults
          to the package itself.

     Example:

          (defpackage "FOO" (:export "BAR") (:lock t) (:implement))
          (defpackage "FOO-INT" (:use "FOO") (:implement "FOO" "FOO-INT"))

          ;;; is equivalent to

          (defpackage "FOO") (:export "BAR"))
          (lock-package "FOO")
          (remove-implementation-package "FOO" "FOO")
          (defpackage "FOO-INT" (:use "BAR"))
          (add-implementation-package "FOO-INT" "FOO")


File: sbcl.info,  Node: Threading,  Next: Timers,  Prev: Package Locks,  Up: Top

12 Threading
************

SBCL supports a fairly low-level threading interface that maps onto the
host operating system's concept of threads or lightweight processes.
This means that threads may take advantage of hardware multiprocessing
on machines that have more than one CPU, but it does not allow Lisp
control of the scheduler.  This is found in the SB-THREAD package.

   This requires Linux (2.6+ or systems with NPTL backports) running on
the x86 or x86-64 architecture, or SunOS (Solaris) on the x86.  Support
for threading on Darwin (Mac OS X) and FreeBSD on the x86 is
experimental.

* Menu:

* Threading basics::
* Special Variables::
* Mutex Support::
* Semaphores::
* Waitqueue/condition variables::
* Sessions/Debugging::
* Foreign threads::
* Implementation (Linux x86/x86-64)::


File: sbcl.info,  Node: Threading basics,  Next: Special Variables,  Up: Threading

12.1 Threading basics
=====================

     (make-thread (lambda () (write-line "Hello, world")))

12.1.1 Thread Objects
---------------------

 -- Structure: sb-thread:thread
     Class precedence list: `thread, structure-object, t'

     Thread type. Do not rely on threads being structs as it may change
     in future versions.

 -- Variable: sb-thread:*current-thread*
     Bound in each thread to the thread itself.

 -- Function: sb-thread:list-all-threads
     Return a list of the live threads. Note that the return value is
     potentially stale even before the function returns, as new threads
     may be created and old ones may exit at any time.

 -- Function: sb-thread:thread-alive-p thread
     Return `t' if `thread' is still alive. Note that the return value
     is potentially stale even before the function returns, as the
     thread may exit at any time.

 -- Function: sb-thread:thread-name instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

12.1.2 Making, Joining, and Yielding Threads
--------------------------------------------

 -- Function: sb-thread:make-thread function &key name
     Create a new thread of `name' that runs `function'. When the
     function returns the thread exits. The return values of `function'
     are kept around and can be retrieved by `join-thread'.

 -- Function: sb-thread:thread-yield
     Yield the processor to other threads.

 -- Function: sb-thread:join-thread thread &key default
     Suspend current thread until `thread' exits. Returns the result
     values of the thread function. If the thread does not exit
     normally, return `default' if given or else signal
     `join-thread-error'.

12.1.3 Asynchronous Operations
------------------------------

 -- Function: sb-thread:interrupt-thread thread function
     Interrupt the live `thread' and make it run `function'. A moderate
     degree of care is expected for use of `interrupt-thread', due to
     its nature: if you interrupt a thread that was holding important
     locks then do something that turns out to need those locks, you
     probably won't like the effect. `function' runs with interrupts
     disabled, but `with-interrupts' is allowed in it. Keep in mind
     that many things may enable interrupts (GET-MUTEX when contended,
     for instance) so the first thing to do is usually a
     `with-interrupts' or a `without-interrupts'. Within a thread
     interrupts are queued, they are run in same the order they were
     sent.

 -- Function: sb-thread:terminate-thread thread
     Terminate the thread identified by `thread', by causing it to run
     `sb-ext:quit' `-' the usual cleanup forms will be evaluated

12.1.4 Miscellaneous Operations
-------------------------------

 -- Function: sb-thread:symbol-value-in-thread symbol thread &optional
          errorp
     Return the local value of `symbol' in `thread', and a secondary
     value of `t' on success.

     If the value cannot be retrieved (because the thread has exited or
     because it has no local binding for NAME) and `errorp' is true
     signals an error of type `symbol-value-in-thread-error'; if
     `errorp' is false returns a primary value of `nil', and a
     secondary value of `nil'.

     Can also be used with `setf' to change the thread-local value of
     `symbol'.

     `symbol-value-in-thread' is primarily intended as a debugging
     tool, and not as a mechanism for inter-thread communication.

12.1.5 Error Conditions
-----------------------

 -- Condition: sb-thread:thread-error
     Class precedence list: `thread-error, error, serious-condition,
     condition, t'

     Conditions of type `thread-error' are signalled when thread
     operations fail.  The offending thread is initialized by the
     `:thread' initialization argument and read by the function
     `thread-error-thread'.

 -- Function: sb-thread:thread-error-thread condition
     Return the offending thread that the `thread-error' pertains to.

 -- Condition: sb-thread:interrupt-thread-error
     Class precedence list: `interrupt-thread-error, thread-error,
     error, serious-condition, condition, t'

     Signalled when interrupting a thread fails because the thread has
     already exited. The offending thread can be accessed using
     `thread-error-thread'.

 -- Condition: sb-thread:join-thread-error
     Class precedence list: `join-thread-error, thread-error, error,
     serious-condition, condition, t'

     Signalled when joining a thread fails due to abnormal exit of the
     thread to be joined. The offending thread can be accessed using
     `thread-error-thread'.


File: sbcl.info,  Node: Special Variables,  Next: Mutex Support,  Prev: Threading basics,  Up: Threading

12.2 Special Variables
======================

The interaction of special variables with multiple threads is mostly as
one would expect, with behaviour very similar to other implementations.

   * global special values are visible across all threads;

   * bindings (e.g. using LET) are local to the thread;

   * threads do not inherit dynamic bindings from the parent thread

   The last point means that

     (defparameter *x* 0)
     (let ((*x* 1))
       (sb-thread:make-thread (lambda () (print *x*))))

   prints `0' and not `1' as of 0.9.6.


File: sbcl.info,  Node: Mutex Support,  Next: Semaphores,  Prev: Special Variables,  Up: Threading

12.3 Mutex Support
==================

Mutexes are used for controlling access to a shared resource. One
thread is allowed to hold the mutex, others which attempt to take it
will be made to wait until it's free. Threads are woken in the order
that they go to sleep.

   There isn't a timeout on mutex acquisition, but the usual
WITH-TIMEOUT macro (which throws a TIMEOUT condition after n seconds)
can be used if you want a bounded wait.

     (defpackage :demo (:use "CL" "SB-THREAD" "SB-EXT"))

     (in-package :demo)

     (defvar *a-mutex* (make-mutex :name "my lock"))

     (defun thread-fn ()
       (format t "Thread ~A running ~%" *current-thread*)
       (with-mutex (*a-mutex*)
         (format t "Thread ~A got the lock~%" *current-thread*)
         (sleep (random 5)))
       (format t "Thread ~A dropped lock, dying now~%" *current-thread*))

     (make-thread #'thread-fn)
     (make-thread #'thread-fn)

 -- Structure: sb-thread:mutex
     Class precedence list: `mutex, structure-object, t'

     Mutex type.

 -- Function: sb-thread:make-mutex &key name %owner
     Create a mutex.

 -- Function: sb-thread:mutex-name instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-thread:mutex-value mutex
     Current owner of the mutex, `nil' if the mutex is free. May return
     a stale value, use `mutex-owner' instead.

 -- Function: sb-thread:get-mutex mutex &optional new-owner waitp
     Acquire `mutex' for `new-owner', which must be a thread or `nil'.
     If `new-owner' is `nil', it defaults to the current thread. If
     `waitp' is non-NIL and the mutex is in use, sleep until it is
     available.

     Note: using `get-mutex' to assign a `mutex' to another thread then
     the current one is not recommended, and liable to be deprecated.

     `get-mutex' is not interrupt safe. The correct way to call it is:

           (WITHOUT-INTERRUPTS
             ...
             (ALLOW-WITH-INTERRUPTS (GET-MUTEX ...))
             ...)

     `without-interrupts' is necessary to avoid an interrupt unwinding
     the call while the mutex is in an inconsistent state while
     `allow-with-interrupts' allows the call to be interrupted from
     sleep.

     It is recommended that you use `with-mutex' instead of calling
     `get-mutex' directly.

 -- Function: sb-thread:release-mutex mutex &key if-not-owner
     Release `mutex' by setting it to `nil'. Wake up threads waiting for
     this mutex.

     `release-mutex' is not interrupt safe: interrupts should be
     disabled around calls to it.

     If the current thread is not the owner of the mutex then it
     silently returns without doing anything (if `if-not-owner' is
     :PUNT), signals a `warning' (if `if-not-owner' is :WARN), or
     releases the mutex anyway (if `if-not-owner' is :FORCE).

 -- Macro: sb-thread:with-mutex (mutex &key value wait-p) &body body
     Acquire `mutex' for the dynamic scope of `body', setting it to
     `new-value' or some suitable default value if `nil'.  If `wait-p'
     is non-NIL and the mutex is in use, sleep until it is available

 -- Macro: sb-thread:with-recursive-lock (mutex) &body body
     Acquires `mutex' for the dynamic scope of `body'. Within that scope
     further recursive lock attempts for the same mutex succeed. It is
     allowed to mix `with-mutex' and `with-recursive-lock' for the same
     mutex provided the default value is used for the mutex.


File: sbcl.info,  Node: Semaphores,  Next: Waitqueue/condition variables,  Prev: Mutex Support,  Up: Threading

12.4 Semaphores
===============

described here should be considered experimental, subject to API
changes without notice.

 -- Structure: sb-thread:semaphore
     Class precedence list: `semaphore, structure-object, t'

     Semaphore type. The fact that a `semaphore' is a `structure-object'
     should be considered an implementation detail, and may change in
     the future.

 -- Function: sb-thread:make-semaphore &key name count
     Create a semaphore with the supplied `count' and `name'.

 -- Function: sb-thread:semaphore-count instance
     Returns the current count of the semaphore `instance'.

 -- Function: sb-thread:semaphore-name instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-thread:signal-semaphore semaphore &optional n
     Increment the count of `semaphore' by `n'. If there are threads
     waiting on this semaphore, then `n' of them is woken up.

 -- Function: sb-thread:wait-on-semaphore semaphore
     Decrement the count of `semaphore' if the count would not be
     negative. Else blocks until the semaphore can be decremented.


File: sbcl.info,  Node: Waitqueue/condition variables,  Next: Sessions/Debugging,  Prev: Semaphores,  Up: Threading

12.5 Waitqueue/condition variables
==================================

These are based on the POSIX condition variable design, hence the
annoyingly CL-conflicting name. For use when you want to check a
condition and sleep until it's true. For example: you have a shared
queue, a writer process checking "queue is empty" and one or more
readers that need to know when "queue is not empty". It sounds simple,
but is astonishingly easy to deadlock if another process runs when you
weren't expecting it to.

   There are three components:

   * the condition itself (not represented in code)

   * the condition variable (a.k.a waitqueue) which proxies for it

   * a lock to hold while testing the condition

   Important stuff to be aware of:

   * when calling condition-wait, you must hold the mutex.
     condition-wait will drop the mutex while it waits, and obtain it
     again before returning for whatever reason;

   * likewise, you must be holding the mutex around calls to
     condition-notify;

   * a process may return from condition-wait in several circumstances:
     it is not guaranteed that the underlying condition has become
     true. You must check that the resource is ready for whatever you
     want to do to it.


     (defvar *buffer-queue* (make-waitqueue))
     (defvar *buffer-lock* (make-mutex :name "buffer lock"))

     (defvar *buffer* (list nil))

     (defun reader ()
       (with-mutex (*buffer-lock*)
         (loop
          (condition-wait *buffer-queue* *buffer-lock*)
          (loop
           (unless *buffer* (return))
           (let ((head (car *buffer*)))
             (setf *buffer* (cdr *buffer*))
             (format t "reader ~A woke, read ~A~%"
                     *current-thread* head))))))

     (defun writer ()
       (loop
        (sleep (random 5))
        (with-mutex (*buffer-lock*)
          (let ((el (intern
                     (string (code-char
                              (+ (char-code #\A) (random 26)))))))
            (setf *buffer* (cons el *buffer*)))
          (condition-notify *buffer-queue*))))

     (make-thread #'writer)
     (make-thread #'reader)
     (make-thread #'reader)

 -- Structure: sb-thread:waitqueue
     Class precedence list: `waitqueue, structure-object, t'

     Waitqueue type.

 -- Function: sb-thread:make-waitqueue &key name
     Create a waitqueue.

 -- Function: sb-thread:waitqueue-name instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-thread:condition-wait queue mutex
     Atomically release `mutex' and enqueue ourselves on `queue'.
     Another thread may subsequently notify us using
     `condition-notify', at which time we reacquire `mutex' and return
     to the caller.

 -- Function: sb-thread:condition-notify queue &optional n
     Notify `n' threads waiting on `queue'. The same mutex that is used
     in the corresponding `condition-wait' must be held by this thread
     during this call.

 -- Function: sb-thread:condition-broadcast queue
     Notify all threads waiting on `queue'.


File: sbcl.info,  Node: Sessions/Debugging,  Next: Foreign threads,  Prev: Waitqueue/condition variables,  Up: Threading

12.6 Sessions/Debugging
=======================

If the user has multiple views onto the same Lisp image (for example,
using multiple terminals, or a windowing system, or network access)
they are typically set up as multiple "sessions" such that each view
has its own collection of foreground/background/stopped threads.  A
thread which wishes to create a new session can use
`sb-thread:with-new-session' to remove itself from the current session
(which it shares with its parent and siblings) and create a fresh one.
# See also `sb-thread:make-listener-thread'.

   Within a single session, threads arbitrate between themselves for the
user's attention.  A thread may be in one of three notional states:
foreground, background, or stopped.  When a background process attempts
to print a repl prompt or to enter the debugger, it will stop and print
a message saying that it has stopped.  The user at his leisure may
switch to that thread to find out what it needs.  If a background
thread enters the debugger, selecting any restart will put it back into
the background before it resumes.  Arbitration for the input stream is
managed by calls to `sb-thread:get-foreground' (which may block) and
`sb-thread:release-foreground'.

   `sb-ext:quit' terminates all threads in the current session, but
leaves other sessions running.


File: sbcl.info,  Node: Foreign threads,  Next: Implementation (Linux x86/x86-64),  Prev: Sessions/Debugging,  Up: Threading

12.7 Foreign threads
====================

Direct calls to `pthread_create' (instead of `MAKE-THREAD') create
threads that SBCL is not aware of, these are called foreign threads.
Currently, it is not possible to run Lisp code in such threads. This
means that the Lisp side signal handlers cannot work.  The best
solution is to start foreign threads with signals blocked, but since
third party libraries may create threads, it is not always feasible to
do so. As a workaround, upon receiving a signal in a foreign thread,
SBCL changes the thread's sigmask to block all signals that it wants to
handle and resends the signal to the current process which should land
in a thread that does not block it, that is, a Lisp thread.

   The resignalling trick cannot work for synchronously triggered
signals (SIGSEGV and co), take care not to trigger any. Resignalling for
synchronously triggered signals in foreign threads is subject to
`--lose-on-corruption', see *Note Runtime Options::.


File: sbcl.info,  Node: Implementation (Linux x86/x86-64),  Prev: Foreign threads,  Up: Threading

12.8 Implementation (Linux x86/x86-64)
======================================

Threading is implemented using pthreads and some Linux specific bits
like futexes.

   On x86 the per-thread local bindings for special variables is
achieved using the %fs segment register to point to a per-thread
storage area.  This may cause interesting results if you link to
foreign code that expects threading or creates new threads, and the
thread library in question uses %fs in an incompatible way. On x86-64
the r12 register has a similar role.

   Queues require the `sys_futex()' system call to be available: this
is the reason for the NPTL requirement.  We test at runtime that this
system call exists.

   Garbage collection is done with the existing Conservative
Generational GC.  Allocation is done in small (typically 8k) regions:
each thread has its own region so this involves no stopping. However,
when a region fills, a lock must be obtained while another is
allocated, and when a collection is required, all processes are
stopped.  This is achieved by sending them signals, which may make for
interesting behaviour if they are interrupted in system calls.  The
streams interface is believed to handle the required system call
restarting correctly, but this may be a consideration when making other
blocking calls e.g. from foreign library code.

   Large amounts of the SBCL library have not been inspected for
thread-safety.  Some of the obviously unsafe areas have large locks
around them, so compilation and fasl loading, for example, cannot be
parallelized.  Work is ongoing in this area.

   A new thread by default is created in the same POSIX process group
and session as the thread it was created by.  This has an impact on
keyboard interrupt handling: pressing your terminal's intr key
(typically `Control-C') will interrupt all processes in the foreground
process group, including Lisp threads that SBCL considers to be
notionally `background'.  This is undesirable, so background threads
are set to ignore the SIGINT signal.

   `sb-thread:make-listener-thread' in addition to creating a new Lisp
session makes a new POSIX session, so that pressing `Control-C' in one
window will not interrupt another listener - this has been found to be
embarrassing.


File: sbcl.info,  Node: Timers,  Next: Networking,  Prev: Threading,  Up: Top

13 Timers
*********

SBCL supports a system-wide event scheduler implemented on top of
`setitimer' that also works with threads but does not require a
separate scheduler thread.

   The following example schedules a timer that writes "Hello, word"
after two seconds.

     (schedule-timer (make-timer (lambda ()
                                   (write-line "Hello, world")
                                   (force-output)))
                     2)

   It should be noted that writing timer functions requires special
care, as the dynamic environment in which they run is unpredictable:
dynamic variable bindings, locks held, etc, all depend on whatever code
was running when the timer fired. The following example should serve as
a cautionary tale:

     (defvar *foo* nil)

     (defun show-foo ()
       (format t "~&foo=~S~%" *foo*)
       (force-output t))

     (defun demo ()
       (schedule-timer (make-timer #'show-foo) 0.5)
       (schedule-timer (make-timer #'show-foo) 1.5)
       (let ((*foo* t))
         (sleep 1.0))
       (let ((*foo* :surprise!))
         (sleep 2.0)))

13.1 Timer Dictionary
=====================

 -- Structure: sb-ext:timer
     Class precedence list: `timer, structure-object, t'

     Timer type. Do not rely on timers being structs as it may change in
     future versions.

 -- Function: sb-ext:make-timer function &key name thread
     Create a timer object that's when scheduled runs `function'. If
     `thread' is a thread then that thread is to be interrupted with
     `function'. If `thread' is `t' then a new thread is created each
     timer `function' is run. If `thread' is `nil' then `function' can
     be run in any thread. When `thread' is not `t', `interrupt-thread'
     is used to run `function' and the ordering guarantees of
     `interrupt-thread' also apply here.  `function' always runs with
     interrupts disabled but `with-interrupts' is allowed.

 -- Function: sb-ext:timer-name timer
     Return the name of `timer'.

 -- Function: sb-ext:timer-scheduled-p timer &key delta
     See if `timer' will still need to be triggered after `delta'
     seconds from now. For timers with a repeat interval it returns
     true.

 -- Function: sb-ext:schedule-timer timer time &key repeat-interval
          absolute-p
     Schedule `timer' to be triggered at `time'. If `absolute-p' then
     `time' is universal time, but non-integral values are also
     allowed, else `time' is measured as the number of seconds from the
     current time. If `repeat-interval' is given, `timer' is
     automatically rescheduled upon expiry.

 -- Function: sb-ext:unschedule-timer timer
     Cancel `timer'. Once this function returns it is guaranteed that
     `timer' shall not be triggered again and there are no unfinished
     triggers.

 -- Function: sb-ext:list-all-timers
     Return a list of all timers in the system.


File: sbcl.info,  Node: Networking,  Next: Profiling,  Prev: Timers,  Up: Top

14 Networking
*************

The `sb-bsd-sockets' module provides a thinly disguised BSD socket API
for SBCL. Ideas have been stolen from the BSD socket API for C and
Graham Barr's IO::Socket classes for Perl.

   Sockets are represented as CLOS objects, and the API naming
conventions attempt to balance between the BSD names and good lisp
style.

* Menu:

* Sockets Overview::
* General Sockets::      Methods applicable to all sockets
* Socket Options::
* INET Domain Sockets::
* Local (Unix) Domain Sockets::
* Name Service::


File: sbcl.info,  Node: Sockets Overview,  Next: General Sockets,  Up: Networking

14.1 Sockets Overview
=====================

Most of the functions are modelled on the BSD socket API.  BSD sockets
are widely supported, portably _("portable" by Unix standards, at
least)_ available on a variety of systems, and documented.  There are
some differences in approach where we have taken advantage of some of
the more useful features of Common Lisp - briefly:

   * Where the C API would typically return -1 and set `errno',
     `sb-bsd-sockets' signals an error. All the errors are subclasses
     of `sb-bsd-sockets:socket-condition' and generally correspond one
     for one with possible `errno' values.

   * We use multiple return values in many places where the C API would
     use pass-by-reference values.

   * We can often avoid supplying an explicit _length_ argument to
     functions because we already know how long the argument is.

   * IP addresses and ports are represented in slightly friendlier
     fashion than "network-endian integers".



File: sbcl.info,  Node: General Sockets,  Next: Socket Options,  Prev: Sockets Overview,  Up: Networking

14.2 General Sockets
====================

 -- Class: sb-bsd-sockets:socket
     Class precedence list: `socket, standard-object, t'

     Slots:
        * `protocol' -- initarg: `:protocol'; reader:
          `sb-bsd-sockets:socket-protocol'

          Protocol used by the socket. If a keyword, the symbol-name of
          the keyword will be passed to `get-protocol-by-name'
          downcased, and the returned value used as protocol. Other
          values are used as-is.

        * `type' -- initarg: `:type'; reader:
          `sb-bsd-sockets:socket-type'

          Type of the socket: `:stream' or `:datagram'.

     Common base class of all sockets, not meant to be directly
     instantiated.

 -- Generic Function: sb-bsd-sockets:socket-bind socket &rest address
     Bind `socket' to `address', which may vary according to socket
     family.  For the `inet' family, pass `address' and `port' as two
     arguments; for `file' address family sockets, pass the filename
     string.  See also bind(2)

 -- Generic Function: sb-bsd-sockets:socket-accept socket
     Perform the accept(2) call, returning a newly-created connected
     socket and the peer address as multiple values

 -- Generic Function: sb-bsd-sockets:socket-connect socket &rest address
     Perform the connect(2) call to connect `socket' to a   remote
     `peer'.  No useful return value.

 -- Generic Function: sb-bsd-sockets:socket-peername socket
     Return the socket's peer; depending on the address   family this
     may return multiple values

 -- Generic Function: sb-bsd-sockets:socket-name socket
     Return the address (as vector of bytes) and port   that the socket
     is bound to, as multiple values.

 -- Generic Function: sb-bsd-sockets:socket-receive socket buffer
          length &key oob peek waitall dontwait element-type
          element-type
     Read `length' octets from `socket' into `buffer' (or a
     freshly-consed buffer if NIL), using recvfrom(2). If `length' is
     `nil', the length of `buffer' is used, so at least one of these
     two arguments must be non-NIL. If `buffer' is supplied, it had
     better be of an element type one octet wide. Returns the buffer,
     its length, and the address of the peer that sent it, as multiple
     values. On datagram sockets, sets MSG_TRUNC so that the actual
     packet length is returned even if the buffer was too small.

 -- Generic Function: sb-bsd-sockets:socket-send socket buffer length
          &key address external-format oob eor dontroute dontwait
          nosignal external-format
     Send `length' octets from `buffer' into `socket', using sendto(2).
     If `buffer' is a string, it will converted to octets according to
     `external-format'. If `length' is `nil', the length of the octet
     buffer is used. The format of `address' depends on the socket type
     (for example for `inet' domain sockets it would be a list of an
     `ip' address and a port). If no socket address is provided,
     send(2) will be called instead. Returns the number of octets
     written.

 -- Generic Function: sb-bsd-sockets:socket-listen socket backlog
     Mark `socket' as willing to accept incoming connections.  `backlog'
     defines the maximum length that the queue of pending connections
     may grow to before new connection attempts are refused.  See also
     listen(2)

 -- Generic Function: sb-bsd-sockets:socket-open-p socket
     Return true if `socket' is open; otherwise, return false.

 -- Generic Function: sb-bsd-sockets:socket-close socket
     Close `socket'.  May throw any kind of error that write(2) would
     have thrown.  If `socket-make-stream' has been called, calls
     `close' on that stream instead

 -- Generic Function: sb-bsd-sockets:socket-make-stream socket &key
          input output element-type external-format buffering timeout
          element-type buffering external-format
     Find or create a `stream' that can be used for `io' on `socket'
     (which must be connected).  Specify whether the stream is for
     `input', `output', or both (it is an error to specify neither).
     `element-type' and `external-format' are as per `open'.  `timeout'
     specifies a read timeout for the stream.

 -- Method: sb-bsd-sockets:socket-make-stream (socket socket) &key
          input output (element-type (quote character)) (buffering
          full) (external-format default) timeout
     Default method for `socket' objects.  An `element-type' of
     `:default' will construct a bivalent stream.  Acceptable values
     for `buffering' are `:full', `:line' and `:none'.  Streams will
     have no `timeout' by default.    The stream for `socket' will be
     cached, and a second invocation of this method will return the
     same stream.  This may lead to oddities if this function is
     invoked with inconsistent arguments (e.g., one might request an
     input stream and get an output stream in response).

 -- Function: sb-bsd-sockets:socket-error where

 -- Generic Function: sb-bsd-sockets:non-blocking-mode socket
     Is `socket' in non-blocking mode?


File: sbcl.info,  Node: Socket Options,  Next: INET Domain Sockets,  Prev: General Sockets,  Up: Networking

14.3 Socket Options
===================

A subset of socket options are supported, using a fairly general
framework which should make it simple to add more as required - see
`SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP' for details. The name mapping
from C is fairly straightforward: `SO_RCVLOWAT' becomes
`sockopt-receive-low-water' and `(setf sockopt-receive-low-water)'.

 -- Function: sb-bsd-sockets:sockopt-reuse-address socket
     Return the value of the `so-reuseaddr' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-keep-alive socket
     Return the value of the `so-keepalive' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-oob-inline socket
     Return the value of the `so-oobinline' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-bsd-compatible socket
     Return the value of the `so-bsdcompat' socket option for `socket'.
     This can also be updated with `setf'. Available only on Linux.

 -- Function: sb-bsd-sockets:sockopt-pass-credentials socket
     Return the value of the `so-passcred' socket option for `socket'.
     This can also be updated with `setf'. Available only on Linux.

 -- Function: sb-bsd-sockets:sockopt-debug socket
     Return the value of the `so-debug' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-dont-route socket
     Return the value of the `so-dontroute' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-broadcast socket
     Return the value of the `so-broadcast' socket option for `socket'.
     This can also be updated with `setf'.

 -- Function: sb-bsd-sockets:sockopt-tcp-nodelay socket
     Return the value of the `tcp-nodelay' socket option for `socket'.
     This can also be updated with `setf'.


File: sbcl.info,  Node: INET Domain Sockets,  Next: Local (Unix) Domain Sockets,  Prev: Socket Options,  Up: Networking

14.4 INET Domain Sockets
========================

The TCP and UDP sockets that you know and love. Some representation
issues:

   * Internet addresses are represented by vectors of (unsigned-byte 8)
     - viz. #(127 0 0 1). Ports are just integers: 6010. No conversion
     between network- and host-order data is needed from the user of
     this package.

   * Socket addresses are represented by the two values for address and
     port, so for example, (socket-connect s #(192 168 1 1) 80).


 -- Class: sb-bsd-sockets:inet-socket
     Class precedence list: `inet-socket, socket, standard-object, t'

     Class representing `tcp' and `udp' sockets.

     Examples:

           (make-instance 'inet-socket :type :stream :protocol :tcp)

           (make-instance 'inet-socket :type :datagram :protocol :udp)

 -- Function: sb-bsd-sockets:make-inet-address dotted-quads
     Return a vector of octets given a string `dotted-quads' in the
     format "127.0.0.1". Signals an error if the string is malformed.

 -- Function: sb-bsd-sockets:get-protocol-by-name name
     Returns the network protocol number associated with the string
     `name', using getprotobyname(2) which typically looks in `nis' or
     /etc/protocols


File: sbcl.info,  Node: Local (Unix) Domain Sockets,  Next: Name Service,  Prev: INET Domain Sockets,  Up: Networking

14.5 Local (Unix) Domain Sockets
================================

Local domain (`AF_LOCAL') sockets are also known as Unix-domain
sockets, but were renamed by POSIX presumably on the basis that they
may be available on other systems too.

   A local socket address is a string, which is used to create a node in
the local filesystem. This means of course that they cannot be used
across a network.

 -- Class: sb-bsd-sockets:local-socket
     Class precedence list: `local-socket, socket, standard-object, t'

     Class representing local domain (AF_LOCAL) sockets, also known as
     unix-domain sockets.


File: sbcl.info,  Node: Name Service,  Prev: Local (Unix) Domain Sockets,  Up: Networking

14.6 Name Service
=================

Presently name service is implemented by calling out to the
`getaddrinfo(3)' and `gethostinfo(3)', or to `gethostbyname(3)'
`gethostbyaddr(3)' on platforms where the preferred functions are not
available. The exact details of the name resolving process (for example
the choice of whether DNS or a hosts file is used for lookup) are
platform dependent.

 -- Class: sb-bsd-sockets:host-ent
     Class precedence list: `host-ent, standard-object, t'

     Slots:
        * `name' -- initarg: `:name'; reader:
          `sb-bsd-sockets:host-ent-name'

          The name of the host

        * `addresses' -- initarg: `:addresses'; reader:
          `sb-bsd-sockets:host-ent-addresses'

          A list of addresses for this host.

     This class represents the results of an address lookup.

 -- Function: sb-bsd-sockets:get-host-by-name host-name
     Returns a `host-ent' instance for `host-name' or signals a
     `name-service-error'.  `host-name' may also be an `ip' address in
     dotted quad notation or some other weird stuff `-' see
     gethostbyname(3) or getaddrinfo(3) for the details.

 -- Function: sb-bsd-sockets:get-host-by-address address
     Returns a `host-ent' instance for `address', which should be a
     vector of  (integer 0 255), or signals a `name-service-error'.
     See gethostbyaddr(3)  or gethostinfo(3) for details.

 -- Generic Function: sb-bsd-sockets:host-ent-address host-ent
     Returns some valid address for `host-ent'.


File: sbcl.info,  Node: Profiling,  Next: Contributed Modules,  Prev: Networking,  Up: Top

15 Profiling
************

SBCL includes both a deterministic profiler, that can collect statistics
on individual functions, and a more "modern" statistical profiler.

   Inlined functions do not appear in the results reported by either.

* Menu:

* Deterministic Profiler::
* Statistical Profiler::


File: sbcl.info,  Node: Deterministic Profiler,  Next: Statistical Profiler,  Up: Profiling

15.1 Deterministic Profiler
===========================

The package `sb-profile' provides a classic, per-function-call profiler.

   *NOTE*: When profiling code executed by multiple threads in
parallel, the consing attributed to each function is inaccurate.

 -- Macro: sb-profile:profile &rest names
     `profile' Name*

     If no names are supplied, return the list of profiled functions.

     If names are supplied, wrap profiling code around the named
     functions.     As in `trace', the names are not evaluated. A
     symbol names a function.     A string names all the functions
     named by symbols in the named    package. If a function is already
     profiled, then unprofile and    reprofile (useful to notice
     function redefinition.)  If a name is    undefined, then we give a
     warning and ignore it. See also    `unprofile', `report' and
     `reset'.

 -- Macro: sb-profile:unprofile &rest names
     Unwrap any profiling code around the named functions, or if no
     names   are given, unprofile all profiled functions. A symbol names
      a function. A string names all the functions named by symbols in
     the   named package. `names' defaults to the list of names of all
     currently   profiled functions.

 -- Function: sb-profile:report
     Report results from profiling. The results are approximately
     adjusted for profiling overhead. The compensation may be rather
     inaccurate when bignums are involved in runtime calculation, as in
     a very-long-running Lisp process.

 -- Function: sb-profile:reset
     Reset the counters for all profiled functions.


File: sbcl.info,  Node: Statistical Profiler,  Prev: Deterministic Profiler,  Up: Profiling

15.2 Statistical Profiler
=========================

The `sb-sprof' module, loadable by
     (require :sb-sprof)
   provides an alternate profiler which works by taking samples of the
program execution at regular intervals, instead of instrumenting
functions like `sb-profile:profile' does. You might find `sb-sprof'
more useful than the deterministic profiler when profiling functions in
the `common-lisp'-package, SBCL internals, or code where the
instrumenting overhead is excessive.

   Additionally `sb-sprof' includes a limited deterministic profiler
which can be used for reporting the amounts of calls to some functions
during

15.2.1 Example Usage
--------------------

     (in-package :cl-user)

     (require :sb-sprof)

     (declaim (optimize speed))

     (defun cpu-test-inner (a i)
       (logxor a
               (* i 5)
               (+ a i)))

     (defun cpu-test (n)
       (let ((a 0))
         (dotimes (i (expt 2 n) a)
           (setf a (cpu-test-inner a i)))))

     ;;;; CPU profiling

     ;;; Take up to 1000 samples of running (CPU-TEST 26), and give a flat
     ;;; table report at the end. Profiling will end one the body has been
     ;;; evaluated once, whether or not 1000 samples have been taken.
     (sb-sprof:with-profiling (:max-samples 1000
                               :report :flat
                               :loop nil)
       (cpu-test 26))

     ;;; Record call counts for functions defined on symbols in the CL-USER
     ;;; package.
     (sb-sprof:profile-call-counts "CL-USER")

     ;;; Take 1000 samples of running (CPU-TEST 24), and give a flat
     ;;; table report at the end. The body will be re-evaluated in a loop
     ;;; until 1000 samples have been taken. A sample count will be printed
     ;;; after each iteration.
     (sb-sprof:with-profiling (:max-samples 1000
                               :report :flat
                               :loop t
                               :show-progress t)
       (cpu-test 24))

     ;;;; Allocation profiling

     (defun foo (&rest args)
       (mapcar (lambda (x) (float x 1d0)) args))

     (defun bar (n)
       (declare (fixnum n))
       (apply #'foo (loop repeat n collect n)))

     (sb-sprof:with-profiling (:max-samples 10000
                               :mode :alloc
                               :report :flat)
       (bar 1000))

15.2.2 Output
-------------

The flat report format will show a table of all functions that the
profiler encountered on the call stack during sampling, ordered by the
number of samples taken while executing that function.

                Self        Total        Cumul
       Nr  Count     %  Count     %  Count     %    Calls  Function
     ------------------------------------------------------------------------
        1     69  24.4     97  34.3     69  24.4 67108864  CPU-TEST-INNER
        2     64  22.6     64  22.6    133  47.0        -  SB-VM::GENERIC-+
        3     39  13.8    256  90.5    172  60.8        1  CPU-TEST
        4     31  11.0     31  11.0    203  71.7        -  SB-KERNEL:TWO-ARG-XOR

   For each function, the table will show three absolute and relative
sample counts. The Self column shows samples taken while directly
executing that function. The Total column shows samples taken while
executing that function or functions called from it (sampled to a
platform-specific depth). The Cumul column shows the sum of all Self
columns up to and including that line in the table.

   Additionally the Calls column will record the amount of calls that
were made to the function during the profiling run. This value will only
be reported for functions that have been explicitly marked for call
counting with `profile-call-counts'.

   The profiler also hooks into the disassembler such that instructions
which have been sampled are annotated with their relative frequency of
sampling.  This information is not stored across different sampling
runs.

     ;      6CF:       702E             JO L4              ; 6/242 samples
     ;      6D1:       D1E3             SHL EBX, 1
     ;      6D3:       702A             JO L4
     ;      6D5: L2:   F6C303           TEST BL, 3         ; 2/242 samples
     ;      6D8:       756D             JNE L8
     ;      6DA:       8BC3             MOV EAX, EBX       ; 5/242 samples
     ;      6DC: L3:   83F900           CMP ECX, 0         ; 4/242 samples

15.2.3 Platform support
-----------------------

This module is known not to work consistently on the Alpha platform,
for technical reasons related to the implementation of a machine
language idiom for marking sections of code to be treated as atomic by
the garbage collector;  However, it should work on other platforms, and
the deficiency on the Alpha will eventually be rectified.

   Allocation profiling is only supported on SBCL builds that use the
generational garbage collector. Tracking of call stacks at a depth of
more than two levels is only supported on x86 and x86-64.

15.2.4 Macros
-------------

 -- Macro: sb-sprof:with-profiling (&key sample-interval alloc-interval
          max-samples reset mode loop max-depth show-progress threads
          report) &body body
     Repeatedly evaluate `body' with statistical profiling turned on.
      In multi-threaded operation, only the thread in which
     `with-profiling'    was evaluated will be profiled by default. If
     you want to profile    multiple threads, invoke the profiler with
     `start-profiling'.

     The following keyword args are recognized:

    _`:sample-interval' <n>_
          Take a sample every <n> seconds. Default is
          `*sample-interval*'.

    _`:alloc-interval' <n>_
          Take a sample every time <n> allocation regions (approximately
              8kB) have been allocated since the last sample. Default
          is      `*alloc-interval*'.

    _`:mode' <mode>_
          If `:cpu', run the profiler in `cpu' profiling mode. If
          `:alloc', run the      profiler in allocation profiling mode.
          If `:time', run the profiler      in wallclock profiling mode.

    _`:max-samples' <max>_
          Repeat evaluating body until <max> samples are taken.
          Default is `*max-samples*'.

    _`:max-depth' <max>_
          Maximum call stack depth that the profiler should consider.
          Only      has an effect on x86 and x86-64.

    _`:report' <type>_
          If specified, call `report' with `:type' <type> at the end.

    _`:reset' <bool>_
          It true, call `reset' at the beginning.

    _`:threads' <list-form>_
          Form that evaluates to the list threads to profile, or `:all'
          to indicate      that all threads should be profiled.
          Defaults to the current      thread. (Note: `start-profiling'
          defaults to all threads.)

          `:threads' has no effect on call-counting at the moment.

          On some platforms (eg. Darwin) the signals used by the
          profiler are      not properly delivered to threads in
          proportion to their `cpu' usage      when doing `:cpu'
          profiling. If you see empty call graphs, or are obviously
          missing several samples from certain threads, you may be
          falling afoul      of this.

    _`:loop' <bool>_
          If true (the default) repeatedly evaluate `body'. If false,
          evaluate      if only once.


 -- Macro: sb-sprof:with-sampling (&optional on) &body body
     Evaluate body with statistical sampling turned on or off.

15.2.5 Functions
----------------

 -- Function: sb-sprof:report &key type max min-percent call-graph
          sort-by sort-order stream show-progress
     Report statistical profiling results.  The following keyword
     args are recognized:

    _`:type' <type>_
          Specifies the type of report to generate.  If `:flat', show
             flat report, if `:graph' show a call graph and a flat
          report.        If nil, don't print out a report.

    _`:stream' <stream>_
          Specify a stream to print the report on.  Default is
          `*standard-output*'.

    _`:max' <max>_
          Don't show more than <max> entries in the flat report.

    _`:min-percent' <min-percent>_
          Don't show functions taking less than <min-percent> of the
            total time in the flat report.

    _`:sort-by' <column>_
          If `:samples', sort flat report by number of samples taken.
              If `:cumulative-samples', sort flat report by cumulative
          number of samples       taken (shows how much time each
          function spent on stack.) Default       is `*report-sort-by*'.

    _`:sort-order' <order>_
          If `:descending', sort flat report in descending order. If
          `:ascending',       sort flat report in ascending order.
          Default is `*report-sort-order*'.

    _`:show-progress' <bool>_
          If true, print progress messages while generating the call
          graph.

    _`:call-graph' <graph>_
          Print a report from <graph> instead of the latest profiling
            results.


     Value of this function is a `call-graph' object representing the
     resulting call-graph, or `nil' if there are no samples (eg. right
     after calling `reset'.)

 -- Function: sb-sprof:reset
     Reset the profiler.

 -- Function: sb-sprof:start-profiling &key max-samples mode
          sample-interval alloc-interval max-depth threads sampling
     Start profiling statistically in the current thread if not already
     profiling.  The following keyword args are recognized:

    _`:sample-interval' <n>_
          Take a sample every <n> seconds.  Default is
          `*sample-interval*'.

    _`:alloc-interval' <n>_
          Take a sample every time <n> allocation regions (approximately
              8kB) have been allocated since the last sample. Default
          is      `*alloc-interval*'.

    _`:mode' <mode>_
          If `:cpu', run the profiler in `cpu' profiling mode. If
          `:alloc', run      the profiler in allocation profiling mode.
          If `:time', run the profiler      in wallclock profiling mode.

    _`:max-samples' <max>_
          Maximum number of samples.  Default is `*max-samples*'.

    _`:max-depth' <max>_
          Maximum call stack depth that the profiler should consider.
          Only      has an effect on x86 and x86-64.

    _`:threads' <list>_
          List threads to profile, or `:all' to indicate that all
          threads should be      profiled. Defaults to `:all'. (Note:
          `with-profiling' defaults to the current      thread.)

          `:threads' has no effect on call-counting at the moment.

          On some platforms (eg. Darwin) the signals used by the
          profiler are      not properly delivered to threads in
          proportion to their `cpu' usage      when doing `:cpu'
          profiling. If you see empty call graphs, or are obviously
          missing several samples from certain threads, you may be
          falling afoul      of this.

    _`:sampling' <bool>_
          If true, the default, start sampling right away.       If
          false, `start-sampling' can be used to turn sampling on.


 -- Function: sb-sprof:stop-profiling
     Stop profiling if profiling.

 -- Function: sb-sprof:profile-call-counts &rest names
     Mark the functions named by `names' as being subject to call
     counting during statistical profiling. If a string is used as a
     name, it will be interpreted as a package name. In this case call
     counting will be done for all functions with names like `x' or
     (SETF X), where `x' is a symbol with the package as its home
     package.

 -- Function: sb-sprof:unprofile-call-counts
     Clear all call counting information. Call counting will be done
     for no functions during statistical profiling.

15.2.6 Variables
----------------

 -- Variable: sb-sprof:*max-samples*
     Default number of traces taken. This variable is somewhat misnamed:
     each trace may actually consist of an arbitrary number of samples,
     depending on the depth of the call stack.

 -- Variable: sb-sprof:*sample-interval*
     Default number of seconds between samples.

15.2.7 Credits
--------------

`sb-sprof' is an SBCL port, with enhancements, of Gerd Moellmann's
statistical profiler for CMUCL.


File: sbcl.info,  Node: Contributed Modules,  Next: Concept Index,  Prev: Profiling,  Up: Top

16 Contributed Modules
**********************

SBCL comes with a number of modules that are not part of the core
system.  These are loaded via `(require :MODULENAME)' (*note
Customization Hooks for Users::).  This section contains documentation
(or pointers to documentation) for some of the contributed modules.

* Menu:

* sb-aclrepl::
* sb-grovel::
* sb-posix::
* sb-md5::
* sb-queue::
* sb-rotate-byte::
* sb-cover::


File: sbcl.info,  Node: sb-aclrepl,  Next: sb-grovel,  Up: Contributed Modules

16.1 sb-aclrepl
===============

The `sb-aclrepl' module offers an Allegro CL-style Read-Eval-Print Loop
for SBCL, with integrated inspector.  Adding a debugger interface is
planned.

16.1.1 Usage
------------

To start `sb-aclrepl' as your read-eval-print loop, put the form
     (require 'sb-aclrepl)

   in your `~/.sbclrc' initialization file.

16.1.2 Example Initialization
-----------------------------

Here's a longer example of a `~/.sbclrc' file that shows off some of
the features of `sb-aclrepl':

     (ignore-errors (require 'sb-aclrepl))

     (when (find-package 'sb-aclrepl)
       (push :aclrepl cl:*features*))
     #+aclrepl
     (progn
       (setq sb-aclrepl:*max-history* 100)
       (setf (sb-aclrepl:alias "asdc")
            #'(lambda (sys) (asdf:operate 'asdf:compile-op sys)))
       (sb-aclrepl:alias "l" (sys) (asdf:operate 'asdf:load-op sys))
       (sb-aclrepl:alias "t" (sys) (asdf:operate 'asdf:test-op sys))
       ;; The 1 below means that two characaters ("up") are required
       (sb-aclrepl:alias ("up" 1 "Use package") (package) (use-package package))
       ;; The 0 below means only the first letter ("r") is required,
       ;; such as ":r base64"
       (sb-aclrepl:alias ("require" 0 "Require module") (sys) (require sys))
       (setq cl:*features* (delete :aclrepl cl:*features*)))

   Questions, comments, or bug reports should be sent to Kevin Rosenberg
(<kevin@rosenberg.net>).

16.1.3 Credits
--------------

Allegro CL is a registered trademark of Franz Inc.


File: sbcl.info,  Node: sb-grovel,  Next: sb-posix,  Prev: sb-aclrepl,  Up: Contributed Modules

16.2 sb-grovel
==============

The `sb-grovel' module helps in generation of foreign function
interfaces. It aids in extracting constants' values from the C compiler
and in generating SB-ALIEN structure and union types, *note Defining
Foreign Types::.

   The ASDF(`http://www.cliki.net/ASDF') component type
GROVEL-CONSTANTS-FILE has its PERFORM operation defined to write out a
C source file, compile it, and run it.  The output from this program is
Lisp, which is then itself compiled and loaded.

   sb-grovel is used in a few contributed modules, and it is currently
compatible only to SBCL. However, if you want to use it, here are a few
directions.

16.2.1 Using sb-grovel in your own ASDF system
----------------------------------------------

  1. Create a Lisp package for the foreign constants/functions to go
     into.

  2. Make your system depend on the 'sb-grovel system.

  3. Create a grovel-constants data file - for an example, see
     example-constants.lisp in the contrib/sb-grovel/ directory in the
     SBCL source distribution.

  4. Add it as a component in your system. e.g.

          (eval-when (:compile-toplevel :load-toplevel :execute)
            (require :sb-grovel))

          (defpackage :example-package.system
                      (:use :cl :asdf :sb-grovel :sb-alien))

          (in-package :example-package.system)

          (defsystem example-system
              :depends-on (sb-grovel)
              :components
              ((:module "sbcl"
                        :components
                        ((:file "defpackage")
                         (grovel-constants-file "example-constants"
                                                :package :example-package)))))

     Make sure to specify the package you chose in step 1

  5. Build stuff.


16.2.2 Contents of a grovel-constants-file
------------------------------------------

The grovel-constants-file, typically named `constants.lisp', comprises
lisp expressions describing the foreign things that you want to grovel
for. A `constants.lisp' file contains two sections:

   * a list of headers to include in the C program, for example:
          ("sys/types.h" "sys/socket.h" "sys/stat.h" "unistd.h" "sys/un.h"
           "netinet/in.h" "netinet/in_systm.h" "netinet/ip.h" "net/if.h"
           "netdb.h" "errno.h" "netinet/tcp.h" "fcntl.h" "signal.h" )

   * A list of sb-grovel clauses describing the things you want to
     grovel from the C compiler, for example:
          ((:integer af-local
                     #+(or sunos solaris) "AF_UNIX"
                     #-(or sunos solaris) "AF_LOCAL"
                     "Local to host (pipes and file-domain).")
           (:structure stat ("struct stat"
                             (integer dev "dev_t" "st_dev")
                             (integer atime "time_t" "st_atime")))
           (:function getpid ("getpid" int )))

   There are two types of things that sb-grovel can sensibly extract
from the C compiler: constant integers and structure layouts. It is also
possible to define foreign functions in the constants.lisp file, but
these definitions don't use any information from the C program; they
expand directly to `sb-alien:define-alien-routine' (*note The
define-alien-routine Macro::) forms.

   Here's how to use the grovel clauses:

   * `:integer' - constant expressions in C. Used in this form:
           (:integer lisp-variable-name "C expression" &optional doc export)

     `"C expression"' will be typically be the name of a constant. But
     other forms are possible.

   * `:enum'
           (:enum lisp-type-name ((lisp-enumerated-name c-enumerated-name) ...)))

     An `sb-alien:enum' type with name `lisp-type-name' will be defined.
     The symbols are the `lisp-enumerated-name's, and the values are
     grovelled from the `c-enumerated-name's.

   * `:structure' - alien structure definitions look like this:
           (:structure lisp-struct-name ("struct c_structure"
                                         (type-designator lisp-element-name
                                          "c_element_type" "c_element_name"
                                          :distrust-length nil)
                                         ; ...
                                         ))

     `type-designator' is a reference to a type whose size (and type
     constraints) will be groveled for. sb-grovel accepts a form of type
     designator that doesn't quite conform to either lisp nor sb-alien's
     type specifiers. Here's a list of type designators that sb-grovel
     currently accepts:
        * `integer' - a C integral type; sb-grovel will infer the exact
          type from size information extracted from the C program. All
          common C integer types can be grovelled for with this type
          designator, but it is not possible to grovel for bit fields
          yet.

        * `(unsigned n)' - an unsigned integer variable that is `n'
          bytes long. No size information from the C program will be
          used.

        * `(signed n)' - an signed integer variable that is `n' bytes
          long. No size information from the C program will be used.

        * `c-string' - an array of `char' in the structure. sb-grovel
          will use the array's length from the C program, unless you
          pass it the `:distrust-length' keyword argument with
          non-`nil' value (this might be required for structures such
          as solaris's `struct dirent').

        * `c-string-pointer' - a pointer to a C string, corresponding to
          the `sb-alien:c-string' type (*note Foreign Type
          Specifiers::).

        * `(array alien-type)' - An array of the previously-declared
          alien type. The array's size will be determined from the
          output of the C program and the alien type's size.

        * `(array alien-type n)' - An array of the previously-declared
          alien type. The array's size will be assumed as being `n'.

     Note that `c-string' and `c-string-pointer' do not have the same
     meaning. If you declare that an element is of type `c-string', it
     will be treated as if the string is a part of the structure,
     whereas if you declare that the element is of type
     `c-string-pointer', a _pointer to a string_ will be the structure
     member.

   * `:function' - alien function definitions are similar to
     `define-alien-routine' definitions, because they expand to such
     forms when the lisp program is loaded. *Note Foreign Function
     Calls::.

          (:function lisp-function-name ("alien_function_name" alien-return-type
                                                               (argument alien-type)
                                                               (argument2 alien-type)))

16.2.3 Programming with sb-grovel's structure types
---------------------------------------------------

Let us assume that you have a grovelled structure definition:
      (:structure mystruct ("struct my_structure"
                            (integer myint "int" "st_int")
                            (c-string mystring "char[]" "st_str")))

   What can you do with it? Here's a short interface document:

   * Creating and destroying objects:
        * Function `(allocate-mystruct)' - allocates an object of type
          `mystruct'and returns a system area pointer to it.

        * Function `(free-mystruct var)' - frees the alien object
          pointed to by VAR.

        * Macro `(with-mystruct var ((member init) [...]) &body body)' -
          allocates an object of type `mystruct' that is valid in BODY.
          If BODY terminates or control unwinds out of BODY, the object
          pointed to by VAR will be deallocated.

   * Accessing structure members:
        * `(mystruct-myint var)' and `(mystruct-mystring var)' return
          the value of the respective fields in `mystruct'.

        * `(setf (mystruct-myint var) new-val)' and `(setf
          (mystruct-mystring var) new-val)' sets the value of the
          respective structure member to the value of NEW-VAL. Notice
          that in `(setf (mystruct-mystring var) new-val)''s case,
          new-val is a lisp string.

16.2.3.1 Traps and Pitfalls
...........................

Basically, you can treat functions and data structure definitions that
sb-grovel spits out as if they were alien routines and types. This has
a few implications that might not be immediately obvious (especially if
you have programmed in a previous version of sb-grovel that didn't use
alien types):

   * You must take care of grovel-allocated structures yourself. They
     are alien types, so the garbage collector will not collect them
     when you drop the last reference.

   * If you use the `with-mystruct' macro, be sure that no references
     to the variable thus allocated leaks out. It will be deallocated
     when the block exits.


File: sbcl.info,  Node: sb-posix,  Next: sb-md5,  Prev: sb-grovel,  Up: Contributed Modules

16.3 sb-posix
=============

Sb-posix is the supported interface for calling out to the operating
system.(1)

   The scope of this interface is "operating system calls on a typical
Unixlike platform".  This is section 2 of the Unix manual, plus section
3 calls that are (a) typically found in libc, but (b) not part of the C
standard.  For example, we intend to provide support for `opendir()'
and `readdir()', but not for `printf()'.  That said, if your favourite
system call is not included yet, you are encouraged to submit a patch
to the SBCL mailing list.

   Some facilities are omitted where they offer absolutely no additional
use over some portable function, or would be actively dangerous to the
consistency of Lisp.  Not all functions are available on all platforms.

* Menu:

* Lisp names for C names::
* Types::
* Function Parameters::
* Function Return Values::
* Lisp objects and C structures::
* Functions with idiosyncratic bindings::

   ---------- Footnotes ----------

   (1) The functionality contained in the package `SB-UNIX' is for SBCL
internal use only; its contents are likely to change from version to
version.


File: sbcl.info,  Node: Lisp names for C names,  Next: Types,  Up: sb-posix

16.3.1 Lisp names for C names
-----------------------------

All symbols are in the `SB-POSIX' package.  This package contains a
Lisp function for each supported Unix system call or function, a
variable or constant for each supported Unix constant, an object type
for each supported Unix structure type, and a slot name for each
supported Unix structure member.  A symbol name is derived from the C
binding's name, by (a) uppercasing, then (b) removing leading
underscores (`#\_') then replacing remaining underscore characters with
the hyphen (`#\-'). The requirement to uppercase is so that in a
standard upcasing reader the user may write `sb-posix:creat' instead of
`sb-posix:|creat|' as would otherise be required.

   No other changes to "Lispify" symbol names are made, so `creat()'
becomes `CREAT', not `CREATE'.

   The user is encouraged not to `(USE-PACKAGE :SB-POSIX)' but instead
to use the `SB-POSIX:' prefix on all references, as some of the symbols
symbols contained in the SB-POSIX package have the same name as CL
symbols (`OPEN', `CLOSE', `SIGNAL' etc).


File: sbcl.info,  Node: Types,  Next: Function Parameters,  Prev: Lisp names for C names,  Up: sb-posix

16.3.2 Types
------------

Generally, marshalling between Lisp and C data types is done using
SBCL's FFI. *Note Foreign Function Interface::.

   Some functions accept objects such as filenames or file descriptors.
In the C binding to POSIX these are represented as strings and small
integers respectively. For the Lisp programmer's convenience we
introduce designators such that CL pathnames or open streams can be
passed to these functions.  For example, `rename' accepts both
pathnames and strings as its arguments.

* Menu:

* File-descriptors::
* Filenames::


File: sbcl.info,  Node: File-descriptors,  Next: Filenames,  Up: Types

16.3.2.1 File-descriptors
.........................

 -- Type: sb-posix:file-descriptor
     A `fixnum' designating a native file descriptor.

     `sb-sys:make-fd-stream' can be used to construct a `file-stream'
     associated with a native file descriptor.

     Note that mixing I/O operations on a `file-stream' with operations
     directly on its descriptor may produce unexpected results if the
     stream is buffered.

 -- Type: sb-posix:file-descriptor-designator
     Designator for a `file-descriptor:' either a fixnum designating
     itself, or a `file-stream' designating the underlying
     file-descriptor.

 -- Function: sb-posix:file-descriptor file-descriptor
     Converts `file-descriptor-designator' into a `file-descriptor'.


File: sbcl.info,  Node: Filenames,  Prev: File-descriptors,  Up: Types

16.3.2.2 Filenames
..................

 -- Type: sb-posix:filename
     A `string' designating a filename in native namestring syntax.

     Note that native namestring syntax is distinct from Lisp
     namestring syntax:

            (pathname "/foo*/bar")

     is a wild pathname with a pattern-matching directory component.
     `sb-ext:parse-native-namestring' may be used to construct Lisp
     pathnames that denote `posix' filenames as understood by system
     calls, and `sb-ext:native-namestring' can be used to coerce them
     into strings in the native namestring syntax.

     Note also that `posix' filename syntax does not distinguish the
     names of files from the names of directories: in order to parse
     the name of a directory in `posix' filename syntax into a pathname
     `my-defaults' for which

            (merge-pathnames (make-pathname :name "FOO" :case :common)
                              my-defaults)

     returns a pathname that denotes a file in the directory, supply a
     true `:as-directory' argument to `sb-ext:parse-native-namestring'.
     Likewise, to supply the name of a directory to a `posix' function
     in non-directory syntax, supply a true `:as-file' argument to
     `sb-ext:native-namestring'.

 -- Type: sb-posix:filename-designator
     Designator for a `filename:' a `string' designating itself, or a
     designator for a `pathname' designating the corresponding native
     namestring.

 -- Function: sb-posix:filename filename
     Converts `filename-designator' into a `filename'.


File: sbcl.info,  Node: Function Parameters,  Next: Function Return Values,  Prev: Types,  Up: sb-posix

16.3.3 Function Parameters
--------------------------

The calling convention is modelled after that of CMUCL's `UNIX'
package: in particular, it's like the C interface except that:

  a. Length arguments are omitted or optional where the sensible value
     is obvious.  For example, `read' would be defined this way:

          (read fd buffer &optional (length (length buffer))) => bytes-read

  b. Where C simulates "out" parameters using pointers (for instance, in
     `pipe()' or `socketpair()') these may be optional or omitted in
     the Lisp interface: if not provided, appropriate objects will be
     allocated and returned (using multiple return values if necessary).

  c. Some functions accept objects such as filenames or file
     descriptors.  Wherever these are specified as such in the C
     bindings, the Lisp interface accepts designators for them as
     specified in the 'Types' section above.

  d. A few functions have been included in sb-posix that do not
     correspond exactly with their C counterparts.  These are described
     in *Note Functions with idiosyncratic bindings::.



File: sbcl.info,  Node: Function Return Values,  Next: Lisp objects and C structures,  Prev: Function Parameters,  Up: sb-posix

16.3.4 Function Return Values
-----------------------------

The return value is usually the same as for the C binding, except in
error cases: where the C function is defined as returning some sentinel
value and setting `errno' on error, we instead signal an error of type
`SYSCALL-ERROR'.  The actual error value (`errno') is stored in this
condition and can be accessed with `SYSCALL-ERRNO'.

   We do not automatically translate the returned value into "Lispy"
objects - for example, `SB-POSIX:OPEN' returns a small integer, not a
stream.  Exception: boolean-returning functions (or, more commonly,
macros) do not return a C integer, but instead a Lisp boolean.


File: sbcl.info,  Node: Lisp objects and C structures,  Next: Functions with idiosyncratic bindings,  Prev: Function Return Values,  Up: sb-posix

16.3.5 Lisp objects and C structures
------------------------------------

Sb-posix provides various Lisp object types to stand in for C
structures in the POSIX library.  Lisp bindings to C functions that
accept, manipulate, or return C structures accept, manipulate, or
return instances of these Lisp types instead of instances of alien
types.

   The names of the Lisp types are chosen according to the general rules
described above.  For example Lisp objects of type `STAT' stand in for
C structures of type `struct stat'.

   Accessors are provided for each standard field in the structure.
These are named `STRUCTURE-NAME-FIELD-NAME' where the two components
are chosen according to the general name conversion rules, with the
exception that in cases where all fields in a given structure have a
common prefix, that prefix is omitted. For example, `stat.st_dev' in C
becomes `STAT-DEV' in Lisp.

   Because sb-posix might not support all semi-standard or
implementation-dependent members of all structure types on your system
(patches welcome), here is an enumeration of all supported Lisp objects
corresponding to supported POSIX structures, and the supported slots
for those structures.

   * flock

      -- Class: sb-posix:flock
          Class precedence list: `flock, standard-object, t'

          Slots:
             * `type' -- initarg: `:type'; reader:
               `sb-posix:flock-type'; writer:
               `(setf sb-posix:flock-type)'

               Type of lock; F_RDLCK, F_WRLCK, F_UNLCK.

             * `whence' -- initarg: `:whence'; reader:
               `sb-posix:flock-whence'; writer:
               `(setf sb-posix:flock-whence)'

               Flag for starting offset.

             * `start' -- initarg: `:start'; reader:
               `sb-posix:flock-start'; writer:
               `(setf sb-posix:flock-start)'

               Relative offset in bytes.

             * `len' -- initarg: `:len'; reader: `sb-posix:flock-len';
               writer: `(setf sb-posix:flock-len)'

               Size; if 0 then until `eof'.

             * `pid' -- reader: `sb-posix:flock-pid'

               Process `id' of the process holding the lock; returned
               with F_GETLK.

          Class representing locks used in fcntl(2).

   * passwd

      -- Class: sb-posix:passwd
          Class precedence list: `passwd, standard-object, t'

          Slots:
             * `name' -- initarg: `:name'; reader:
               `sb-posix:passwd-name'; writer:
               `(setf sb-posix:passwd-name)'

               User's login name.

             * `passwd' -- initarg: `:passwd'; reader:
               `sb-posix:passwd-passwd'; writer:
               `(setf sb-posix:passwd-passwd)'

               The account's encrypted password.

             * `uid' -- initarg: `:uid'; reader: `sb-posix:passwd-uid';
               writer: `(setf sb-posix:passwd-uid)'

               Numerical user `id'.

             * `gid' -- initarg: `:gid'; reader: `sb-posix:passwd-gid';
               writer: `(setf sb-posix:passwd-gid)'

               Numerical group `id'.

             * `gecos' -- initarg: `:gecos'; reader:
               `sb-posix:passwd-gecos'; writer:
               `(setf sb-posix:passwd-gecos)'

               User's name or comment field.

             * `dir' -- initarg: `:dir'; reader: `sb-posix:passwd-dir';
               writer: `(setf sb-posix:passwd-dir)'

               Initial working directory.

             * `shell' -- initarg: `:shell'; reader:
               `sb-posix:passwd-shell'; writer:
               `(setf sb-posix:passwd-shell)'

               Program to use as shell.

          Instances of this class represent entries in
           the system's user database.

   * stat

      -- Class: sb-posix:stat
          Class precedence list: `stat, standard-object, t'

          Slots:
             * `mode' -- initarg: `:mode'; reader: `sb-posix:stat-mode'

               Mode of file.

             * `ino' -- initarg: `:ino'; reader: `sb-posix:stat-ino'

               File serial number.

             * `dev' -- initarg: `:dev'; reader: `sb-posix:stat-dev'

               Device `id' of device containing file.

             * `nlink' -- initarg: `:nlink'; reader:
               `sb-posix:stat-nlink'

               Number of hard links to the file.

             * `uid' -- initarg: `:uid'; reader: `sb-posix:stat-uid'

               User `id' of file.

             * `gid' -- initarg: `:gid'; reader: `sb-posix:stat-gid'

               Group `id' of file.

             * `size' -- initarg: `:size'; reader: `sb-posix:stat-size'

               For regular files, the file size in
                  bytes.  For symbolic links, the length
                         in bytes of the filename contained in
                               the symbolic link.

             * `atime' -- initarg: `:atime'; reader:
               `sb-posix:stat-atime'

               Time of last access.

             * `mtime' -- initarg: `:mtime'; reader:
               `sb-posix:stat-mtime'

               Time of last data modification.

             * `ctime' -- initarg: `:ctime'; reader:
               `sb-posix:stat-ctime'

               Time of last status change

          Instances of this class represent Posix file
           metadata.

   * termios

      -- Class: sb-posix:termios
          Class precedence list: `termios, standard-object, t'

          Slots:
             * `iflag' -- initarg: `:iflag'; reader:
               `sb-posix:termios-iflag'; writer:
               `(setf sb-posix:termios-iflag)'

               Input modes.

             * `oflag' -- initarg: `:oflag'; reader:
               `sb-posix:termios-oflag'; writer:
               `(setf sb-posix:termios-oflag)'

               Output modes.

             * `cflag' -- initarg: `:cflag'; reader:
               `sb-posix:termios-cflag'; writer:
               `(setf sb-posix:termios-cflag)'

               Control modes.

             * `lflag' -- initarg: `:lflag'; reader:
               `sb-posix:termios-lflag'; writer:
               `(setf sb-posix:termios-lflag)'

               Local modes.

          Instances of this class represent I/O
          characteristics of the terminal.

   * timeval

      -- Class: sb-posix:timeval
          Class precedence list: `timeval, standard-object, t'

          Slots:
             * `sec' -- initarg: `:tv-sec'; reader:
               `sb-posix:timeval-sec'; writer:
               `(setf sb-posix:timeval-sec)'

               Seconds.

             * `usec' -- initarg: `:tv-usec'; reader:
               `sb-posix:timeval-usec'; writer:
               `(setf sb-posix:timeval-usec)'

               Microseconds.

          Instances of this class represent time values.


File: sbcl.info,  Node: Functions with idiosyncratic bindings,  Prev: Lisp objects and C structures,  Up: sb-posix

16.3.6 Functions with idiosyncratic bindings
--------------------------------------------

A few functions in sb-posix don't correspond directly to their C
counterparts.

   * getcwd

      -- Function: sb-posix:getcwd
          Returns the process's current working directory as a string.

   * readlink

      -- Function: sb-posix:readlink pathspec
          Returns the resolved target of a symbolic link as a string.

   * syslog

      -- Function: sb-posix:syslog priority format &rest args
          Send a message to the syslog facility, with severity level
          `priority'.  The message will be formatted as by `cl:format'
          (rather than C's printf) with format string `format' and
          arguments `args'.


File: sbcl.info,  Node: sb-md5,  Next: sb-queue,  Prev: sb-posix,  Up: Contributed Modules

16.4 sb-md5
===========

The `sb-md5' module implements the RFC1321 MD5 Message Digest
Algorithm. [FIXME cite]

 -- Function: sb-md5:md5sum-file pathname
     Calculate the MD5 message-digest of the file designated by
     pathname.

 -- Function: sb-md5:md5sum-sequence sequence &key start end
     Calculate the MD5 message-digest of data bounded by `start' and
     `end' in `sequence' , which must be a vector with element-type
     (UNSIGNED-BYTE 8).

 -- Function: sb-md5:md5sum-stream stream
     Calculate an MD5 message-digest of the contents of `stream', whose
     element-type has to be (UNSIGNED-BYTE 8).

 -- Function: sb-md5:md5sum-string string &key external-format start end
     Calculate the MD5 message-digest of the binary representation of
     `string' (as octets) in `external-format'. The boundaries `start'
     and `end' refer to character positions in the string, not to octets
     in the resulting binary representation.

16.4.1 Credits
--------------

The implementation for CMUCL was largely done by Pierre Mai, with help
from members of the `cmucl-help' mailing list.  Since CMUCL and SBCL
are similar in many respects, it was not too difficult to extend the
low-level implementation optimizations for CMUCL to SBCL.  Following
this, SBCL's compiler was extended to implement efficient compilation
of modular arithmetic (*note Modular arithmetic::), which enabled the
implementation to be expressed in portable arithmetical terms, apart
from the use of `rotate-byte' for bitwise rotation.  


File: sbcl.info,  Node: sb-queue,  Next: sb-rotate-byte,  Prev: sb-md5,  Up: Contributed Modules

16.5 sb-queue
=============

The `sb-queue' module, loadable by
     (require :sb-queue)
   provides a thread-safe lockless FIFO queues.

 -- Structure: sb-queue:queue
     Class precedence list: `queue, structure-object, t'

     Lock-free thread safe queue. `enqueue' can be used to add objects
     to the queue, and `dequeue' retrieves items from the queue in
     `fifo' order.

 -- Function: sb-queue:dequeue queue
     Retrieves the oldest value in `queue' and returns it as the
     primary value, and `t' as secondary value. If the queue is empty,
     returns `nil' as both primary and secondary value.

 -- Function: sb-queue:enqueue value queue
     Adds `value' to the end of `queue'. Returns `value'.

 -- Function: sb-queue:list-queue-contents queue
     Returns the contents of `queue' as a list without removing them
     from the `queue'. Mainly useful for manual examination of queue
     state.

 -- Function: sb-queue:make-queue &key name initial-contents
     Returns a new `queue' with `name' and contents of the
     `initial-contents' sequence enqueued.

 -- Function: sb-queue:queue-count queue
     Returns the number of objects in `queue'. Mainly useful for manual
     examination of queue state, and in `print-object' methods:
     inefficient as it walks the entire queue.

 -- Function: sb-queue:queue-empty-p queue
     Returns `t' if `queue' is empty, `nil' otherwise.

 -- Function: sb-queue:queue-name instance
     Name of a `queue'. Can be assingned to using `setf'. Queue names
     can be arbitrary printable objects, and need not be unique.

 -- Function: sb-queue:queuep object
     Returns true if argument is a `queue', `nil' otherwise.


File: sbcl.info,  Node: sb-rotate-byte,  Next: sb-cover,  Prev: sb-queue,  Up: Contributed Modules

16.6 sb-rotate-byte
===================

The `sb-rotate-byte' module offers an interface to bitwise rotation,
with an efficient implementation for operations which can be performed
directly using the platform's arithmetic routines.  It implements the
specification at `http://www.cliki.net/ROTATE-BYTE'.

   Bitwise rotation is a component of various cryptographic or hashing
algorithms: MD5, SHA-1, etc.; often these algorithms are specified on
32-bit rings.  [FIXME cite cite cite].

 -- Function: sb-rotate-byte:rotate-byte count bytespec integer
     Rotates a field of bits within `integer'; specifically, returns an
     integer that contains the bits of `integer' rotated `count' times
     leftwards within the byte specified by `bytespec', and elsewhere
     contains the bits of `integer'.


File: sbcl.info,  Node: sb-cover,  Prev: sb-rotate-byte,  Up: Contributed Modules

16.7 sb-cover
=============

The `sb-cover' module provides a code coverage tool for SBCL. The tool
has support for expression coverage, and for some branch coverage.
Coverage reports are only generated for code compiled using
`compile-file' with the value of the `sb-cover:store-coverage-data'
optimization quality set to 3.

   As of SBCL 1.0.6 `sb-cover' is still experimental, and the
interfaces documented here might change in later versions.

16.7.1 Example Usage
--------------------

     ;;; Load SB-COVER
     (require :sb-cover)

     ;;; Turn on generation of code coverage instrumentation in the compiler
     (declaim (optimize sb-cover:store-coverage-data))

     ;;; Load some code, ensuring that it's recompiled with the new optimization
     ;;; policy.
     (asdf:oos 'asdf:load-op :cl-ppcre-test :force t)

     ;;; Run the test suite.
     (cl-ppcre-test:test)

     ;;; Produce a coverage report
     (sb-cover:report "/tmp/report/")

     ;;; Turn off instrumentation
     (declaim (optimize (sb-cover:store-coverage-data 0)))

16.7.2 Functions
----------------

 -- Function: sb-cover:report directory &key form-mode external-format
     Print a code coverage report of all instrumented files into
     `directory'.  If `directory' does not exist, it will be created.
     The main report will be printed to the file cover-index.html. The
     external format of the source files can be specified with the
     `external-format' parameter.

     If the keyword argument `form-mode' has the value `:car', the
     annotations in the coverage report will be placed on the CARs of
     any cons-forms, while if it has the value `:whole' the whole form
     will be annotated (the default).  The former mode shows explicitly
     which forms were instrumented, while the latter mode is generally
     easier to read.

 -- Function: sb-cover:reset-coverage
     Reset all coverage data back to the `Not executed` state.

 -- Function: sb-cover:clear-coverage
     Clear all files from the coverage database. The files will be
     re-entered into the database when the `fasl' files (produced by
     compiling `store-coverage-data' optimization policy set to 3) are
     loaded again into the image.

 -- Function: sb-cover:save-coverage
     Returns an opaque representation of the current code coverage
     state.  The only operation that may be done on the state is
     passing it to `restore-coverage'. The representation is guaranteed
     to be readably printable.  A representation that has been printed
     and read back will work identically in `restore-coverage'.

 -- Function: sb-cover:save-coverage-in-file pathname
     Call `save-coverage' and write the results of that operation into
     the file designated by `pathname'.

 -- Function: sb-cover:restore-coverage coverage-state
     Restore the code coverage data back to an earlier state produced by
     `save-coverage'.

 -- Function: sb-cover:restore-coverage-from-file pathname
     `read' the contents of the file designated by `pathname' and pass
     the result to `restore-coverage'.


File: sbcl.info,  Node: Concept Index,  Next: Function Index,  Prev: Contributed Modules,  Up: Top

Appendix A Concept Index
************************

[index]
* Menu:

* Actual Source <1>:                     The Parts of a Compiler Diagnostic.
                                                               (line 53)
* Actual Source:                         The Original and Actual Source.
                                                               (line  6)
* Arithmetic, hardware <1>:              Modular arithmetic.   (line  6)
* Arithmetic, hardware:                  sb-rotate-byte.       (line  6)
* Arithmetic, modular <1>:               sb-rotate-byte.       (line  6)
* Arithmetic, modular:                   Modular arithmetic.   (line  6)
* Availability of debug variables:       Variable Value Availability.
                                                               (line  6)
* Block compilation, debugger implications: Entry Point Details.
                                                               (line  6)
* Block, basic:                          Source Location Availability.
                                                               (line  6)
* Block, start location:                 Source Location Availability.
                                                               (line  6)
* Cleanup, stack frame kind:             Entry Point Details.  (line  6)
* Code Coverage:                         sb-cover.             (line  6)
* Compatibility with other Lisps:        Getting Existing Programs to Run.
                                                               (line  6)
* Compile time type errors:              Type Errors at Compile Time.
                                                               (line  6)
* Compiler Diagnostic Severity:          Diagnostic Severity.  (line  6)
* Compiler messages:                     Diagnostic Messages.  (line  6)
* Debug optimization quality <1>:        Debugger Policy Control.
                                                               (line  6)
* Debug optimization quality <2>:        Variable Value Availability.
                                                               (line  6)
* Debug optimization quality:            Source Location Availability.
                                                               (line  6)
* Debug variables:                       Variable Access.      (line  6)
* Debugger:                              Debugger.             (line  6)
* Declarations:                          Package Lock Violations.
                                                               (line  9)
* Dynamic-extent declaration:            Dynamic-extent allocation.
                                                               (line  6)
* Efficiency:                            Efficiency.           (line  6)
* Entry points, external:                Entry Point Details.  (line  6)
* Errors, run-time:                      Unknown Locations and Interrupts.
                                                               (line  6)
* Existing programs, to run:             Getting Existing Programs to Run.
                                                               (line  6)
* External entry points:                 Entry Point Details.  (line  6)
* External, stack frame kind:            Entry Point Details.  (line  6)
* Foreign Function Interface, generation: sb-grovel.           (line  6)
* Function, tracing:                     Function Tracing.     (line  6)
* Garbage Collection, conservative:      History and Implementation of SBCL.
                                                               (line 62)
* Garbage Collection, generational:      History and Implementation of SBCL.
                                                               (line 33)
* Hashing, cryptographic:                sb-md5.               (line  6)
* Inline expansion <1>:                  Debugger Policy Control.
                                                               (line  6)
* Inline expansion:                      Open Coding and Inline Expansion.
                                                               (line  6)
* Interpreter:                           Interpreter.          (line  6)
* Interrupts:                            Unknown Locations and Interrupts.
                                                               (line  6)
* Locations, unknown:                    Unknown Locations and Interrupts.
                                                               (line  6)
* Logical pathnames:                     Lisp Pathnames.       (line 12)
* Macroexpansion:                        The Processing Path.  (line  6)
* Macroexpansion, errors during:         Errors During Macroexpansion.
                                                               (line  6)
* Messages, Compiler:                    Diagnostic Messages.  (line  6)
* Modular arithmetic <1>:                sb-rotate-byte.       (line  6)
* Modular arithmetic:                    Modular arithmetic.   (line  6)
* Open-coding:                           Open Coding and Inline Expansion.
                                                               (line  6)
* Operating System Interface:            sb-posix.             (line  6)
* Optimize declaration:                  Debugger Policy Control.
                                                               (line  6)
* Optional, stack frame kind:            Entry Point Details.  (line  6)
* Original Source <1>:                   The Original and Actual Source.
                                                               (line  6)
* Original Source:                       The Parts of a Compiler Diagnostic.
                                                               (line 35)
* Packages, locked:                      Package Locks.        (line  6)
* Pathnames:                             Pathnames.            (line  6)
* Pathnames, logical:                    Lisp Pathnames.       (line 12)
* Policy, debugger:                      Debugger Policy Control.
                                                               (line  6)
* Posix:                                 sb-posix.             (line  6)
* Precise type checking:                 Precise Type Checking.
                                                               (line  6)
* Processing Path <1>:                   The Processing Path.  (line  6)
* Processing Path:                       The Parts of a Compiler Diagnostic.
                                                               (line 42)
* Profiling:                             Profiling.            (line  6)
* Profiling, deterministic:              Deterministic Profiler.
                                                               (line  6)
* Profiling, statistical:                Statistical Profiler. (line  6)
* Queue, FIFO:                           sb-queue.             (line  6)
* Read errors, compiler:                 Read Errors.          (line  6)
* Read-Eval-Print Loop:                  sb-aclrepl.           (line  6)
* Recursion, tail:                       Debug Tail Recursion. (line  6)
* REPL:                                  sb-aclrepl.           (line  6)
* Semi-inline expansion:                 Debugger Policy Control.
                                                               (line  6)
* Severity of compiler messages:         Diagnostic Severity.  (line  6)
* Single Stepping:                       Single Stepping.      (line  6)
* Slot access:                           Slot access.          (line  6)
* Sockets, Networking:                   Networking.           (line  6)
* Source location printing, debugger:    Source Location Printing.
                                                               (line  6)
* Source-to-source transformation:       The Processing Path.  (line  6)
* Stack frames:                          Stack Frames.         (line  6)
* Static functions:                      Open Coding and Inline Expansion.
                                                               (line  6)
* Stepper:                               Single Stepping.      (line  6)
* System Calls:                          sb-posix.             (line  6)
* Tail recursion:                        Debug Tail Recursion. (line  6)
* Tracing:                               Function Tracing.     (line  6)
* Type checking, at compile time:        Type Errors at Compile Time.
                                                               (line  6)
* Type checking, precise:                Precise Type Checking.
                                                               (line  6)
* Types, portability:                    Getting Existing Programs to Run.
                                                               (line  6)
* Unknown code locations:                Unknown Locations and Interrupts.
                                                               (line  6)
* Validity of debug variables:           Variable Value Availability.
                                                               (line  6)
* Variables, debugger access:            Variable Access.      (line  6)


File: sbcl.info,  Node: Function Index,  Next: Variable Index,  Prev: Concept Index,  Up: Top

Appendix B Function Index
*************************

[index]
* Menu:

* (setf logical-pathname-translations):  Lisp Pathnames.      (line  12)
* (setf sb-mop:slot-value-using-class):  Metaobject Protocol. (line  85)
* (setf slot-value-using-class):         Metaobject Protocol. (line  85)
* ?:                                     Information Commands.
                                                              (line  11)
* abort:                                 Exiting Commands.    (line  20)
* addr:                                  Coercing Foreign Values.
                                                              (line   7)
* alien-funcall:                         The alien-funcall Primitive.
                                                              (line   7)
* alien-sap:                             Coercing Foreign Values.
                                                              (line  27)
* backtrace:                             Information Commands.
                                                              (line  26)
* bottom:                                Stack Motion.        (line  22)
* cast:                                  Coercing Foreign Values.
                                                              (line  13)
* cl:close:                              Methods common to all streams.
                                                              (line  15)
* cl:ed:                                 Customization Hooks for Users.
                                                              (line  30)
* cl:make-hash-table:                    Hash Table Extensions.
                                                              (line  11)
* cl:require:                            Customization Hooks for Users.
                                                              (line  14)
* cl:step:                               Single Stepping.     (line  37)
* cl:stream-element-type:                Methods common to all streams.
                                                              (line  10)
* cl:trace:                              Function Tracing.    (line  12)
* cl:untrace:                            Function Tracing.    (line 113)
* class-name:                            Metaobject Protocol. (line 103)
* class-of:                              Metaobject Protocol. (line  40)
* class-prototype:                       Metaobject Protocol. (line  33)
* compute-effective-method:              Metaobject Protocol. (line  10)
* continue:                              Exiting Commands.    (line  16)
* declare:                               Package Lock Violations.
                                                              (line   9)
* defclass:                              Metaobject Protocol. (line 103)
* defconstant:                           Defining Constants.  (line   6)
* define-alien-routine:                  The define-alien-routine Macro.
                                                              (line   8)
* define-alien-variable:                 External Foreign Variables.
                                                              (line  25)
* defmethod:                             Metaobject Protocol. (line 117)
* defpackage <1>:                        Implementation Packages.
                                                              (line   6)
* defpackage:                            Package Lock Dictionary.
                                                              (line  99)
* deref:                                 Accessing Foreign Values.
                                                              (line   7)
* describe:                              Information Commands.
                                                              (line  14)
* disable-package-locks:                 Package Lock Violations.
                                                              (line   9)
* down:                                  Stack Motion.        (line  15)
* enable-package-locks:                  Package Lock Violations.
                                                              (line   9)
* ensure-class:                          Metaobject Protocol. (line 103)
* ensure-class-using-class:              Metaobject Protocol. (line 103)
* ensure-generic-function:               Metaobject Protocol. (line  24)
* error:                                 Information Commands.
                                                              (line  22)
* extern-alien:                          External Foreign Variables.
                                                              (line  55)
* finalize-inheritance:                  Metaobject Protocol. (line  33)
* find-class:                            Metaobject Protocol. (line 103)
* find-method:                           Metaobject Protocol. (line 131)
* flet:                                  Package Lock Violations.
                                                              (line   9)
* frame:                                 Stack Motion.        (line  25)
* free-alien:                            Foreign Dynamic Allocation.
                                                              (line  42)
* generic-function-declarations:         Metaobject Protocol. (line  24)
* get-errno:                             External Foreign Variables.
                                                              (line  47)
* help:                                  Information Commands.
                                                              (line  10)
* inspect:                               Tools To Help Developers.
                                                              (line   6)
* int-sap:                               Accessing Foreign Values.
                                                              (line  36)
* intern-eql-specializer:                Metaobject Protocol. (line 117)
* labels:                                Package Lock Violations.
                                                              (line   9)
* let:                                   Package Lock Violations.
                                                              (line   9)
* let*:                                  Package Lock Violations.
                                                              (line   9)
* list-locals:                           Variable Access.     (line  28)
* logical-pathname-translations:         Lisp Pathnames.      (line  12)
* macrolet:                              Package Lock Violations.
                                                              (line   9)
* make-alien:                            Foreign Dynamic Allocation.
                                                              (line  14)
* make-method-lambda:                    Metaobject Protocol. (line 117)
* make-method-specializers-form:         Metaobject Protocol. (line 117)
* name-conflict-symbols:                 Resolution of Name Conflicts.
                                                              (line   6)
* next:                                  Single Stepping.     (line  26)
* out:                                   Single Stepping.     (line  30)
* parse-specializer-using-class:         Metaobject Protocol. (line 131)
* print:                                 Information Commands.
                                                              (line  18)
* restart:                               Exiting Commands.    (line  12)
* restart-frame:                         Exiting Commands.    (line  31)
* return:                                Exiting Commands.    (line  25)
* rotate-byte:                           sb-md5.              (line  38)
* safety:                                Declarations as Assertions.
                                                              (line   6)
* sap-alien:                             Coercing Foreign Values.
                                                              (line  20)
* sap-ref-32:                            Accessing Foreign Values.
                                                              (line  39)
* sap=:                                  Accessing Foreign Values.
                                                              (line  44)
* satisfies:                             Handling of Types.   (line  17)
* sb-alien:addr:                         Coercing Foreign Values.
                                                              (line   7)
* sb-alien:alien-funcall:                The alien-funcall Primitive.
                                                              (line   7)
* sb-alien:alien-sap:                    Coercing Foreign Values.
                                                              (line  27)
* sb-alien:cast:                         Coercing Foreign Values.
                                                              (line  13)
* sb-alien:define-alien-routine:         The define-alien-routine Macro.
                                                              (line   8)
* sb-alien:define-alien-variable:        External Foreign Variables.
                                                              (line  25)
* sb-alien:deref:                        Accessing Foreign Values.
                                                              (line   7)
* sb-alien:extern-alien:                 External Foreign Variables.
                                                              (line  55)
* sb-alien:free-alien:                   Foreign Dynamic Allocation.
                                                              (line  42)
* sb-alien:get-errno:                    External Foreign Variables.
                                                              (line  47)
* sb-alien:load-shared-object:           Loading Shared Object Files.
                                                              (line  10)
* sb-alien:make-alien:                   Foreign Dynamic Allocation.
                                                              (line  14)
* sb-alien:sap-alien:                    Coercing Foreign Values.
                                                              (line  20)
* sb-alien:slot:                         Accessing Foreign Values.
                                                              (line  17)
* sb-alien:with-alien:                   Local Foreign Variables.
                                                              (line   7)
* sb-bsd-sockets:get-host-by-address:    Name Service.        (line  36)
* sb-bsd-sockets:get-host-by-name:       Name Service.        (line  30)
* sb-bsd-sockets:get-protocol-by-name:   INET Domain Sockets. (line  34)
* sb-bsd-sockets:host-ent-address:       Name Service.        (line  41)
* sb-bsd-sockets:make-inet-address:      INET Domain Sockets. (line  30)
* sb-bsd-sockets:non-blocking-mode:      General Sockets.     (line 110)
* sb-bsd-sockets:socket-accept:          General Sockets.     (line  33)
* sb-bsd-sockets:socket-bind:            General Sockets.     (line  27)
* sb-bsd-sockets:socket-close:           General Sockets.     (line  82)
* sb-bsd-sockets:socket-connect:         General Sockets.     (line  37)
* sb-bsd-sockets:socket-error:           General Sockets.     (line 108)
* sb-bsd-sockets:socket-listen:          General Sockets.     (line  73)
* sb-bsd-sockets:socket-make-stream:     General Sockets.     (line  89)
* sb-bsd-sockets:socket-name:            General Sockets.     (line  45)
* sb-bsd-sockets:socket-open-p:          General Sockets.     (line  79)
* sb-bsd-sockets:socket-peername:        General Sockets.     (line  41)
* sb-bsd-sockets:socket-receive:         General Sockets.     (line  51)
* sb-bsd-sockets:socket-send:            General Sockets.     (line  63)
* sb-bsd-sockets:sockopt-broadcast:      Socket Options.      (line  41)
* sb-bsd-sockets:sockopt-bsd-compatible: Socket Options.      (line  25)
* sb-bsd-sockets:sockopt-debug:          Socket Options.      (line  33)
* sb-bsd-sockets:sockopt-dont-route:     Socket Options.      (line  37)
* sb-bsd-sockets:sockopt-keep-alive:     Socket Options.      (line  17)
* sb-bsd-sockets:sockopt-oob-inline:     Socket Options.      (line  21)
* sb-bsd-sockets:sockopt-pass-credentials: Socket Options.    (line  29)
* sb-bsd-sockets:sockopt-reuse-address:  Socket Options.      (line  13)
* sb-bsd-sockets:sockopt-tcp-nodelay:    Socket Options.      (line  45)
* sb-cover:clear-coverage:               sb-cover.            (line  58)
* sb-cover:report:                       sb-cover.            (line  41)
* sb-cover:reset-coverage:               sb-cover.            (line  55)
* sb-cover:restore-coverage:             sb-cover.            (line  75)
* sb-cover:restore-coverage-from-file:   sb-cover.            (line  79)
* sb-cover:save-coverage:                sb-cover.            (line  64)
* sb-cover:save-coverage-in-file:        sb-cover.            (line  71)
* sb-debug:var:                          Variable Access.     (line  36)
* sb-ext:add-implementation-package:     Package Lock Dictionary.
                                                              (line  80)
* sb-ext:array-storage-vector:           Miscellaneous Extensions.
                                                              (line   7)
* sb-ext:cancel-finalization:            Garbage Collection.  (line  61)
* sb-ext:defglobal:                      Global and Always-Bound variables.
                                                              (line   7)
* sb-ext:define-hash-table-test:         Hash Table Extensions.
                                                              (line  73)
* sb-ext:disable-package-locks:          Package Lock Violations.
                                                              (line   9)
* sb-ext:enable-package-locks:           Package Lock Violations.
                                                              (line   9)
* sb-ext:finalize:                       Garbage Collection.  (line  15)
* sb-ext:hash-table-synchronized-p:      Hash Table Extensions.
                                                              (line 140)
* sb-ext:hash-table-weakness:            Hash Table Extensions.
                                                              (line 144)
* sb-ext:list-all-timers:                Timers.              (line  79)
* sb-ext:lock-package:                   Package Lock Dictionary.
                                                              (line  59)
* sb-ext:make-timer:                     Timers.              (line  48)
* sb-ext:make-weak-pointer:              Garbage Collection.  (line  64)
* sb-ext:muffle-conditions:              Controlling Verbosity.
                                                              (line  32)
* sb-ext:name-conflict-symbols:          Resolution of Name Conflicts.
                                                              (line   6)
* sb-ext:native-namestring:              Native Filenames.    (line  41)
* sb-ext:native-pathname:                Native Filenames.    (line  37)
* sb-ext:package-implemented-by-list:    Package Lock Dictionary.
                                                              (line  69)
* sb-ext:package-implements-list:        Package Lock Dictionary.
                                                              (line  74)
* sb-ext:package-locked-error-symbol:    Package Lock Dictionary.
                                                              (line  51)
* sb-ext:package-locked-p:               Package Lock Dictionary.
                                                              (line  55)
* sb-ext:parse-native-namestring:        Native Filenames.    (line  27)
* sb-ext:posix-getenv:                   Querying the process environment.
                                                              (line  10)
* sb-ext:process-alive-p:                Running external programs.
                                                              (line 129)
* sb-ext:process-close:                  Running external programs.
                                                              (line 149)
* sb-ext:process-core-dumped:            Running external programs.
                                                              (line 145)
* sb-ext:process-error:                  Running external programs.
                                                              (line 125)
* sb-ext:process-exit-code:              Running external programs.
                                                              (line 141)
* sb-ext:process-input:                  Running external programs.
                                                              (line 117)
* sb-ext:process-kill:                   Running external programs.
                                                              (line 153)
* sb-ext:process-output:                 Running external programs.
                                                              (line 121)
* sb-ext:process-p:                      Running external programs.
                                                              (line 114)
* sb-ext:process-status:                 Running external programs.
                                                              (line 132)
* sb-ext:process-wait:                   Running external programs.
                                                              (line 136)
* sb-ext:purify:                         Efficiency Hacks.    (line  18)
* sb-ext:quit:                           Quit.                (line  12)
* sb-ext:remove-implementation-package:  Package Lock Dictionary.
                                                              (line  86)
* sb-ext:run-program:                    Running external programs.
                                                              (line  11)
* sb-ext:save-lisp-and-die:              Saving a Core Image. (line  13)
* sb-ext:schedule-timer:                 Timers.              (line  67)
* sb-ext:timer-name:                     Timers.              (line  58)
* sb-ext:timer-scheduled-p:              Timers.              (line  61)
* sb-ext:truly-the:                      Efficiency Hacks.    (line  41)
* sb-ext:unlock-package:                 Package Lock Dictionary.
                                                              (line  64)
* sb-ext:unmuffle-conditions:            Controlling Verbosity.
                                                              (line  38)
* sb-ext:unschedule-timer:               Timers.              (line  74)
* sb-ext:weak-pointer-value:             Garbage Collection.  (line  67)
* sb-ext:with-locked-hash-table:         Hash Table Extensions.
                                                              (line 131)
* sb-ext:with-unlocked-packages:         Package Lock Dictionary.
                                                              (line  95)
* sb-ext:without-package-locks:          Package Lock Dictionary.
                                                              (line  91)
* sb-gray:stream-advance-to-column:      Character output stream methods.
                                                              (line  10)
* sb-gray:stream-clear-input:            Input stream methods.
                                                              (line  10)
* sb-gray:stream-clear-output:           Output stream methods.
                                                              (line  10)
* sb-gray:stream-file-position:          Methods common to all streams.
                                                              (line  21)
* sb-gray:stream-finish-output:          Output stream methods.
                                                              (line  14)
* sb-gray:stream-force-output:           Output stream methods.
                                                              (line  19)
* sb-gray:stream-fresh-line:             Character output stream methods.
                                                              (line  19)
* sb-gray:stream-line-column:            Character output stream methods.
                                                              (line  25)
* sb-gray:stream-line-length:            Character output stream methods.
                                                              (line  34)
* sb-gray:stream-listen:                 Character input stream methods.
                                                              (line  36)
* sb-gray:stream-peek-char:              Character input stream methods.
                                                              (line  10)
* sb-gray:stream-read-byte:              Binary stream methods.
                                                              (line  10)
* sb-gray:stream-read-char:              Character input stream methods.
                                                              (line  24)
* sb-gray:stream-read-char-no-hang:      Character input stream methods.
                                                              (line  16)
* sb-gray:stream-read-line:              Character input stream methods.
                                                              (line  30)
* sb-gray:stream-read-sequence:          Input stream methods.
                                                              (line  15)
* sb-gray:stream-start-line-p:           Character output stream methods.
                                                              (line  37)
* sb-gray:stream-terpri:                 Character output stream methods.
                                                              (line  52)
* sb-gray:stream-unread-char:            Character input stream methods.
                                                              (line  43)
* sb-gray:stream-write-byte:             Binary stream methods.
                                                              (line  14)
* sb-gray:stream-write-char:             Character output stream methods.
                                                              (line  56)
* sb-gray:stream-write-sequence:         Output stream methods.
                                                              (line  24)
* sb-gray:stream-write-string:           Character output stream methods.
                                                              (line  62)
* sb-md5:md5sum-file:                    sb-md5.              (line  10)
* sb-md5:md5sum-sequence:                sb-md5.              (line  14)
* sb-md5:md5sum-stream:                  sb-md5.              (line  19)
* sb-md5:md5sum-string:                  sb-md5.              (line  23)
* sb-mop:class-prototype:                Metaobject Protocol. (line  33)
* sb-mop:compute-effective-method:       Metaobject Protocol. (line  10)
* sb-mop:ensure-class:                   Metaobject Protocol. (line 103)
* sb-mop:ensure-class-using-class:       Metaobject Protocol. (line 103)
* sb-mop:finalize-inheritance:           Metaobject Protocol. (line  33)
* sb-mop:generic-function-declarations:  Metaobject Protocol. (line  24)
* sb-mop:intern-eql-specializer:         Metaobject Protocol. (line 117)
* sb-mop:make-method-lambda:             Metaobject Protocol. (line 117)
* sb-mop:slot-boundp-using-class:        Metaobject Protocol. (line  85)
* sb-mop:slot-value-using-class:         Metaobject Protocol. (line  85)
* sb-mop:validate-superclass:            Metaobject Protocol. (line  33)
* sb-pcl:make-method-specializers-form:  Metaobject Protocol. (line 117)
* sb-pcl:parse-specializer-using-class:  Metaobject Protocol. (line 131)
* sb-pcl:unparse-specializer-using-class: Metaobject Protocol.
                                                              (line 131)
* sb-posix:file-descriptor:              File-descriptors.    (line  22)
* sb-posix:filename:                     Filenames.           (line  40)
* sb-posix:getcwd:                       Functions with idiosyncratic bindings.
                                                              (line  12)
* sb-posix:readlink:                     Functions with idiosyncratic bindings.
                                                              (line  17)
* sb-posix:syslog:                       Functions with idiosyncratic bindings.
                                                              (line  22)
* sb-profile:profile:                    Deterministic Profiler.
                                                              (line  12)
* sb-profile:report:                     Deterministic Profiler.
                                                              (line  33)
* sb-profile:reset:                      Deterministic Profiler.
                                                              (line  39)
* sb-profile:unprofile:                  Deterministic Profiler.
                                                              (line  26)
* sb-queue:dequeue:                      sb-queue.            (line  18)
* sb-queue:enqueue:                      sb-queue.            (line  23)
* sb-queue:list-queue-contents:          sb-queue.            (line  26)
* sb-queue:make-queue:                   sb-queue.            (line  31)
* sb-queue:queue-count:                  sb-queue.            (line  35)
* sb-queue:queue-empty-p:                sb-queue.            (line  40)
* sb-queue:queue-name:                   sb-queue.            (line  43)
* sb-queue:queuep:                       sb-queue.            (line  47)
* sb-rotate-byte:rotate-byte:            sb-rotate-byte.      (line  16)
* sb-sprof:profile-call-counts:          Statistical Profiler.
                                                              (line 294)
* sb-sprof:report:                       Statistical Profiler.
                                                              (line 199)
* sb-sprof:reset:                        Statistical Profiler.
                                                              (line 243)
* sb-sprof:start-profiling:              Statistical Profiler.
                                                              (line 247)
* sb-sprof:stop-profiling:               Statistical Profiler.
                                                              (line 291)
* sb-sprof:unprofile-call-counts:        Statistical Profiler.
                                                              (line 302)
* sb-sprof:with-profiling:               Statistical Profiler.
                                                              (line 135)
* sb-sprof:with-sampling:                Statistical Profiler.
                                                              (line 192)
* sb-sys:int-sap:                        Accessing Foreign Values.
                                                              (line  36)
* sb-sys:sap-ref-32:                     Accessing Foreign Values.
                                                              (line  39)
* sb-sys:sap=:                           Accessing Foreign Values.
                                                              (line  44)
* sb-thread:condition-broadcast:         Waitqueue/condition variables.
                                                              (line  91)
* sb-thread:condition-notify:            Waitqueue/condition variables.
                                                              (line  86)
* sb-thread:condition-wait:              Waitqueue/condition variables.
                                                              (line  80)
* sb-thread:get-mutex:                   Mutex Support.       (line  48)
* sb-thread:interrupt-thread:            Threading basics.    (line  55)
* sb-thread:join-thread:                 Threading basics.    (line  46)
* sb-thread:list-all-threads:            Threading basics.    (line  21)
* sb-thread:make-mutex:                  Mutex Support.       (line  37)
* sb-thread:make-semaphore:              Semaphores.          (line  17)
* sb-thread:make-thread:                 Threading basics.    (line  38)
* sb-thread:make-waitqueue:              Waitqueue/condition variables.
                                                              (line  73)
* sb-thread:mutex-name:                  Mutex Support.       (line  40)
* sb-thread:mutex-value:                 Mutex Support.       (line  44)
* sb-thread:release-mutex:               Mutex Support.       (line  72)
* sb-thread:semaphore-count:             Semaphores.          (line  20)
* sb-thread:semaphore-name:              Semaphores.          (line  23)
* sb-thread:signal-semaphore:            Semaphores.          (line  27)
* sb-thread:symbol-value-in-thread:      Threading basics.    (line  76)
* sb-thread:terminate-thread:            Threading basics.    (line  68)
* sb-thread:thread-alive-p:              Threading basics.    (line  26)
* sb-thread:thread-error-thread:         Threading basics.    (line 104)
* sb-thread:thread-name:                 Threading basics.    (line  31)
* sb-thread:thread-yield:                Threading basics.    (line  43)
* sb-thread:wait-on-semaphore:           Semaphores.          (line  31)
* sb-thread:waitqueue-name:              Waitqueue/condition variables.
                                                              (line  76)
* sb-thread:with-mutex:                  Mutex Support.       (line  84)
* sb-thread:with-recursive-lock:         Mutex Support.       (line  89)
* slot:                                  Accessing Foreign Values.
                                                              (line  17)
* slot-boundp-using-class:               Metaobject Protocol. (line  85)
* slot-value-using-class:                Metaobject Protocol. (line  85)
* source:                                Source Location Printing.
                                                              (line  11)
* start:                                 Single Stepping.     (line  15)
* step:                                  Single Stepping.     (line  21)
* stop:                                  Single Stepping.     (line  34)
* subtypep:                              Metaobject Protocol. (line  40)
* symbol-macrolet:                       Package Lock Violations.
                                                              (line   9)
* top:                                   Stack Motion.        (line  18)
* toplevel:                              Exiting Commands.    (line   9)
* trace:                                 Tools To Help Developers.
                                                              (line   6)
* typep:                                 Metaobject Protocol. (line  40)
* unparse-specializer-using-class:       Metaobject Protocol. (line 131)
* up:                                    Stack Motion.        (line  11)
* validate-superclass:                   Metaobject Protocol. (line  33)
* with-alien:                            Local Foreign Variables.
                                                              (line   7)
* with-compilation-unit:                 The Parts of a Compiler Diagnostic.
                                                              (line  21)


File: sbcl.info,  Node: Variable Index,  Next: Type Index,  Prev: Function Index,  Up: Top

Appendix C Variable Index
*************************

[index]
* Menu:

* *package*:                             Implementation Packages.
                                                              (line   6)
* *posix-argv* <1>:                      Command-line arguments.
                                                              (line   6)
* *posix-argv*:                          Shebang Scripts.     (line   6)
* sb-debug:*max-trace-indentation*:      Function Tracing.    (line 120)
* sb-debug:*trace-encapsulate-default*:  Function Tracing.    (line 124)
* sb-debug:*trace-indentation-step*:     Function Tracing.    (line 117)
* sb-debug:*trace-values*:               Function Tracing.    (line 127)
* sb-ext:*after-gc-hooks*:               Garbage Collection.  (line  72)
* sb-ext:*compiler-print-variable-alist*: Controlling Verbosity.
                                                              (line  47)
* sb-ext:*core-pathname*:                Saving a Core Image. (line 110)
* sb-ext:*debug-print-variable-alist*:   Debugger Command Loop.
                                                              (line  28)
* sb-ext:*ed-functions*:                 Customization Hooks for Users.
                                                              (line  37)
* sb-ext:*evaluator-mode*:               Interpreter.         (line   6)
* sb-ext:*exit-hooks*:                   Initialization and Exit Hooks.
                                                              (line  15)
* sb-ext:*init-hooks*:                   Initialization and Exit Hooks.
                                                              (line   9)
* sb-ext:*invoke-debugger-hook*:         Debugger Invocation. (line  29)
* sb-ext:*module-provider-functions*:    Customization Hooks for Users.
                                                              (line  23)
* sb-ext:*muffled-warnings*:             Customization Hooks for Users.
                                                              (line  46)
* sb-ext:*posix-argv* <1>:               Command-line arguments.
                                                              (line   6)
* sb-ext:*posix-argv*:                   Shebang Scripts.     (line   6)
* sb-ext:*save-hooks*:                   Saving a Core Image. (line 101)
* sb-ext:*stack-allocate-dynamic-extent*: Dynamic-extent allocation.
                                                              (line  17)
* sb-sprof:*max-samples*:                Statistical Profiler.
                                                              (line 309)
* sb-sprof:*sample-interval*:            Statistical Profiler.
                                                              (line 314)
* sb-thread:*current-thread*:            Threading basics.    (line  18)


File: sbcl.info,  Node: Type Index,  Next: Colophon,  Prev: Variable Index,  Up: Top

Appendix D Type Index
*********************

[index]
* Menu:

* code-deletion-note:                    Diagnostic Severity. (line   6)
* compiler-note:                         Diagnostic Severity. (line   6)
* error:                                 Diagnostic Severity. (line   6)
* funcallable-standard-class:            Metaobject Protocol. (line  33)
* funcallable-standard-object:           Metaobject Protocol. (line  67)
* function:                              Metaobject Protocol. (line  15)
* generic-function:                      Metaobject Protocol. (line  15)
* name-conflict:                         Resolution of Name Conflicts.
                                                              (line   6)
* package-error:                         Package Lock Violations.
                                                              (line   6)
* package-lock-violation:                Package Lock Violations.
                                                              (line   6)
* package-locked-error:                  Package Lock Violations.
                                                              (line   6)
* sb-bsd-sockets:host-ent:               Name Service.        (line  14)
* sb-bsd-sockets:inet-socket:            INET Domain Sockets. (line  19)
* sb-bsd-sockets:local-socket:           Local (Unix) Domain Sockets.
                                                              (line  15)
* sb-bsd-sockets:socket:                 General Sockets.     (line   7)
* sb-ext:always-bound:                   Global and Always-Bound variables.
                                                              (line  30)
* sb-ext:code-deletion-note:             Diagnostic Severity. (line  42)
* sb-ext:compiler-note:                  Diagnostic Severity. (line  34)
* sb-ext:disable-package-locks:          Package Lock Dictionary.
                                                              (line   7)
* sb-ext:enable-package-locks:           Package Lock Dictionary.
                                                              (line  15)
* sb-ext:global:                         Global and Always-Bound variables.
                                                              (line  19)
* sb-ext:name-conflict:                  Resolution of Name Conflicts.
                                                              (line   6)
* sb-ext:package-lock-violation <1>:     Package Lock Dictionary.
                                                              (line  24)
* sb-ext:package-lock-violation <2>:     Package Lock Violations.
                                                              (line   6)
* sb-ext:package-lock-violation:         Package Lock Dictionary.
                                                              (line  24)
* sb-ext:package-locked-error <1>:       Package Lock Dictionary.
                                                              (line  31)
* sb-ext:package-locked-error <2>:       Package Lock Violations.
                                                              (line   6)
* sb-ext:package-locked-error:           Package Lock Dictionary.
                                                              (line  31)
* sb-ext:symbol-package-locked-error <1>: Package Lock Dictionary.
                                                              (line  40)
* sb-ext:symbol-package-locked-error <2>: Package Lock Violations.
                                                              (line   6)
* sb-ext:symbol-package-locked-error:    Package Lock Dictionary.
                                                              (line  40)
* sb-ext:timer:                          Timers.              (line  42)
* sb-gray:fundamental-binary-input-stream: Gray Streams classes.
                                                              (line  51)
* sb-gray:fundamental-binary-output-stream: Gray Streams classes.
                                                              (line  59)
* sb-gray:fundamental-binary-stream:     Gray Streams classes.
                                                              (line  33)
* sb-gray:fundamental-character-input-stream: Gray Streams classes.
                                                              (line  67)
* sb-gray:fundamental-character-output-stream: Gray Streams classes.
                                                              (line  75)
* sb-gray:fundamental-character-stream:  Gray Streams classes.
                                                              (line  44)
* sb-gray:fundamental-input-stream:      Gray Streams classes.
                                                              (line  15)
* sb-gray:fundamental-output-stream:     Gray Streams classes.
                                                              (line  24)
* sb-gray:fundamental-stream:            Gray Streams classes.
                                                              (line   9)
* sb-mop:funcallable-standard-class:     Metaobject Protocol. (line  33)
* sb-mop:funcallable-standard-object:    Metaobject Protocol. (line  67)
* sb-posix:file-descriptor:              File-descriptors.    (line   7)
* sb-posix:file-descriptor-designator:   File-descriptors.    (line  17)
* sb-posix:filename:                     Filenames.           (line   7)
* sb-posix:filename-designator:          Filenames.           (line  35)
* sb-posix:flock:                        Lisp objects and C structures.
                                                              (line  32)
* sb-posix:passwd:                       Lisp objects and C structures.
                                                              (line  68)
* sb-posix:stat:                         Lisp objects and C structures.
                                                              (line 116)
* sb-posix:termios:                      Lisp objects and C structures.
                                                              (line 172)
* sb-posix:timeval:                      Lisp objects and C structures.
                                                              (line 205)
* sb-queue:queue:                        sb-queue.            (line  11)
* sb-thread:interrupt-thread-error:      Threading basics.    (line 107)
* sb-thread:join-thread-error:           Threading basics.    (line 115)
* sb-thread:mutex:                       Mutex Support.       (line  32)
* sb-thread:semaphore:                   Semaphores.          (line  10)
* sb-thread:thread:                      Threading basics.    (line  12)
* sb-thread:thread-error:                Threading basics.    (line  95)
* sb-thread:waitqueue:                   Waitqueue/condition variables.
                                                              (line  68)
* standard-class:                        Metaobject Protocol. (line  33)
* standard-generic-function:             Metaobject Protocol. (line  15)
* standard-object:                       Metaobject Protocol. (line  15)
* style-warning:                         Diagnostic Severity. (line   6)
* symbol-package-locked-error:           Package Lock Violations.
                                                              (line   6)
* warning:                               Diagnostic Severity. (line   6)


File: sbcl.info,  Node: Colophon,  Prev: Type Index,  Up: Top

Colophon
********

This manual is maintained in Texinfo, and automatically translated into
other forms (e.g. HTML or pdf). If you're _reading_ this manual in one
of these non-Texinfo translated forms, that's fine, but if you want to
_modify_ this manual, you are strongly advised to seek out a Texinfo
version and modify that instead of modifying a translated version. Even
better might be to seek out _the_ Texinfo version (maintained at the
time of this writing as part of the SBCL project at
`http://sbcl.sourceforge.net/') and submit a patch.



Tag Table:
Node: Top645
Node: Getting Support and Reporting Bugs1584
Node: Volunteer Support1838
Node: Commercial Support2934
Node: Reporting Bugs4213
Node: Introduction6978
Node: ANSI Conformance7530
Node: Extensions7811
Node: Idiosyncrasies11731
Node: Declarations12136
Node: FASL Format12487
Node: Compiler-only Implementation13604
Node: Defining Constants14232
Node: Style Warnings15998
Node: Development Tools17244
Node: Editor Integration17489
Ref: Editor Integration-Footnote-118205
Node: Language Reference18351
Node: Generating Executables18738
Node: More SBCL Information19252
Node: SBCL Homepage19552
Node: Online Documentation20007
Node: Additional Documentation Files20785
Node: Internals Documentation21585
Node: More Common Lisp Information22255
Node: Internet Community22551
Node: Third-party Libraries23079
Node: Common Lisp Books23405
Node: History and Implementation of SBCL25667
Node: Starting and Stopping31192
Node: Starting SBCL31468
Node: Running from Shell31672
Node: Running from Emacs32511
Node: Shebang Scripts32962
Node: Stopping SBCL33503
Node: Quit33738
Ref: Function sb-ext:quit34052
Node: End of File34316
Node: Saving a Core Image34627
Ref: Function sb-ext:save-lisp-and-die34974
Ref: Variable sb-ext:*save-hooks*39161
Ref: Variable sb-ext:*core-pathname*39536
Node: Exit on Errors39629
Node: Command Line Options40043
Node: Runtime Options41736
Node: Toplevel Options43854
Node: Initialization Files46114
Node: Initialization and Exit Hooks47350
Ref: Variable sb-ext:*init-hooks*47595
Ref: Variable sb-ext:*exit-hooks*47861
Node: Compiler48162
Node: Diagnostic Messages48890
Node: Controlling Verbosity49126
Ref: Variable sb-ext:*compiler-print-variable-alist*50753
Node: Diagnostic Severity51532
Ref: Condition sb-ext:compiler-note52697
Ref: Condition sb-ext:code-deletion-note53011
Node: Understanding Compiler Diagnostics53270
Node: The Parts of a Compiler Diagnostic54027
Node: The Original and Actual Source59155
Node: The Processing Path60881
Node: Handling of Types62433
Node: Declarations as Assertions63464
Node: Precise Type Checking65553
Node: Getting Existing Programs to Run66461
Ref: Getting Existing Programs to Run-Footnote-171363
Node: Implementation Limitations71503
Node: Compiler Policy72996
Ref: Compiler Policy-Footnote-174044
Node: Compiler Errors74156
Node: Type Errors at Compile Time74411
Node: Errors During Macroexpansion76154
Node: Read Errors77113
Node: Open Coding and Inline Expansion77436
Node: Interpreter79722
Node: Debugger80390
Node: Debugger Entry80892
Node: Debugger Banner81072
Node: Debugger Invocation82323
Ref: Variable sb-ext:*invoke-debugger-hook*83428
Node: Debugger Command Loop84056
Ref: Variable sb-ext:*debug-print-variable-alist*85308
Node: Stack Frames85939
Node: Stack Motion86800
Node: How Arguments are Printed87667
Node: Function Names89932
Node: Entry Point Details90380
Node: Debug Tail Recursion91479
Node: Unknown Locations and Interrupts92799
Node: Variable Access94428
Node: Variable Value Availability96916
Ref: Variable Value Availability-Footnote-1100156
Node: Note On Lexical Variable Access100375
Ref: Note On Lexical Variable Access-Footnote-1101253
Node: Source Location Printing101351
Node: How the Source is Found103604
Node: Source Location Availability105832
Node: Debugger Policy Control107555
Node: Exiting Commands111276
Node: Information Commands112750
Node: Function Tracing113700
Ref: Macro common-lisp:trace114078
Ref: Macro common-lisp:untrace118790
Ref: Variable sb-debug:*trace-indentation-step*118934
Ref: Variable sb-debug:*max-trace-indentation*119041
Ref: Variable sb-debug:*trace-encapsulate-default*119179
Ref: Variable sb-debug:*trace-values*119295
Node: Single Stepping119441
Ref: Macro common-lisp:step120715
Node: Efficiency121005
Node: Slot access121283
Node: Dynamic-extent allocation123199
Ref: Variable sb-ext:*stack-allocate-dynamic-extent*123840
Node: Modular arithmetic127373
Node: Global and Always-Bound variables129006
Ref: Macro sb-ext:defglobal129228
Node: Miscellaneous Efficiency Issues130530
Node: Beyond the ANSI Standard134470
Node: Garbage Collection135106
Ref: Function sb-ext:finalize135722
Ref: Function sb-ext:cancel-finalization137564
Ref: Function sb-ext:make-weak-pointer137656
Ref: Function sb-ext:weak-pointer-value137769
Ref: Variable sb-ext:*after-gc-hooks*138009
Node: Metaobject Protocol138229
Node: Support For Unix145080
Node: Command-line arguments145368
Node: Querying the process environment145617
Ref: Function sb-ext:posix-getenv145922
Node: Running external programs146091
Ref: Function sb-ext:run-program146335
Ref: Function sb-ext:process-p151198
Ref: Function sb-ext:process-input151298
Ref: Function sb-ext:process-output151478
Ref: Function sb-ext:process-error151659
Ref: Function sb-ext:process-alive-p151839
Ref: Function sb-ext:process-status151947
Ref: Function sb-ext:process-wait152118
Ref: Function sb-ext:process-exit-code152348
Ref: Function sb-ext:process-core-dumped152532
Ref: Function sb-ext:process-close152718
Ref: Function sb-ext:process-kill152851
Ref: Running external programs-Footnote-1153242
Node: Customization Hooks for Users153872
Ref: Function common-lisp:require154342
Ref: Variable sb-ext:*module-provider-functions*154879
Ref: Function common-lisp:ed155124
Ref: Variable sb-ext:*ed-functions*155483
Ref: Variable sb-ext:*muffled-warnings*155835
Node: Tools To Help Developers156069
Node: Resolution of Name Conflicts156645
Node: Hash Table Extensions157327
Ref: Function common-lisp:make-hash-table157633
Ref: Macro sb-ext:define-hash-table-test160857
Ref: Macro sb-ext:with-locked-hash-table163265
Ref: Function sb-ext:hash-table-synchronized-p163736
Ref: Function sb-ext:hash-table-weakness163928
Node: Miscellaneous Extensions164114
Ref: Function sb-ext:array-storage-vector164311
Node: Stale Extensions164975
Node: Efficiency Hacks166051
Ref: Function sb-ext:purify166885
Ref: Special-Operator sb-ext:truly-the167933
Node: Foreign Function Interface168823
Node: Introduction to the Foreign Function Interface169996
Node: Foreign Types172322
Node: Defining Foreign Types172905
Node: Foreign Types and Lisp Types173552
Node: Foreign Type Specifiers174688
Node: Operations On Foreign Values183081
Node: Accessing Foreign Values183577
Node: Coercing Foreign Values185878
Node: Foreign Dynamic Allocation187247
Node: Foreign Variables189419
Node: Local Foreign Variables189775
Node: External Foreign Variables191152
Node: Foreign Data Structure Examples193822
Node: Loading Shared Object Files195409
Ref: Function sb-alien:load-shared-object195732
Node: Foreign Function Calls197563
Node: The alien-funcall Primitive198825
Node: The define-alien-routine Macro200854
Node: define-alien-routine Example203957
Node: Calling Lisp From C204691
Node: Step-By-Step Example of the Foreign Function Interface206166
Node: Pathnames210496
Node: Lisp Pathnames210680
Node: Native Filenames211361
Ref: Function sb-ext:parse-native-namestring212583
Ref: Function sb-ext:native-pathname213212
Ref: Function sb-ext:native-namestring213388
Node: Extensible Streams215550
Node: Bivalent Streams216233
Node: Gray Streams216972
Node: Gray Streams classes217781
Ref: Class sb-gray:fundamental-stream217987
Ref: Class sb-gray:fundamental-input-stream218150
Ref: Class sb-gray:fundamental-output-stream218451
Ref: Class sb-gray:fundamental-binary-stream218757
Ref: Class sb-gray:fundamental-character-stream219179
Ref: Class sb-gray:fundamental-binary-input-stream219429
Ref: Class sb-gray:fundamental-binary-output-stream219768
Ref: Class sb-gray:fundamental-character-input-stream220111
Ref: Class sb-gray:fundamental-character-output-stream220440
Node: Methods common to all streams220773
Ref: Generic-Function common-lisp:stream-element-type221077
Ref: Generic-Function common-lisp:close221314
Ref: Generic-Function sb-gray:stream-file-position221569
Node: Input stream methods221754
Ref: Generic-Function sb-gray:stream-clear-input222047
Ref: Generic-Function sb-gray:stream-read-sequence222220
Node: Character input stream methods222373
Ref: Generic-Function sb-gray:stream-peek-char222684
Ref: Generic-Function sb-gray:stream-read-char-no-hang222956
Ref: Generic-Function sb-gray:stream-read-char223411
Ref: Generic-Function sb-gray:stream-read-line223709
Ref: Generic-Function sb-gray:stream-listen224021
Ref: Generic-Function sb-gray:stream-unread-char224369
Node: Output stream methods224631
Ref: Generic-Function sb-gray:stream-clear-output224905
Ref: Generic-Function sb-gray:stream-finish-output225095
Ref: Generic-Function sb-gray:stream-force-output225342
Ref: Generic-Function sb-gray:stream-write-sequence225520
Node: Binary stream methods225675
Ref: Generic-Function sb-gray:stream-read-byte225963
Ref: Generic-Function sb-gray:stream-write-byte226132
Node: Character output stream methods226303
Ref: Generic-Function sb-gray:stream-advance-to-column226627
Ref: Generic-Function sb-gray:stream-fresh-line227152
Ref: Generic-Function sb-gray:stream-line-column227453
Ref: Generic-Function sb-gray:stream-line-length227961
Ref: Generic-Function sb-gray:stream-start-line-p228063
Ref: Generic-Function sb-gray:stream-terpri228995
Ref: Generic-Function sb-gray:stream-write-char229174
Ref: Generic-Function sb-gray:stream-write-string229413
Node: Gray Streams examples229824
Node: Character counting input stream230518
Node: Output prefixing character stream234469
Node: Simple Streams237407
Node: Package Locks238192
Node: Package Lock Concepts238802
Node: Package Lock Overview239124
Node: Implementation Packages239926
Node: Package Lock Violations240575
Node: Package Locks in Compiled Code242291
Node: Operations Violating Package Locks243466
Node: Package Lock Dictionary246734
Ref: Condition sb-ext:package-lock-violation247629
Ref: Condition sb-ext:package-locked-error247900
Ref: Condition sb-ext:symbol-package-locked-error248235
Ref: Function sb-ext:package-locked-p248865
Ref: Function sb-ext:lock-package249042
Ref: Function sb-ext:unlock-package249244
Ref: Function sb-ext:package-implemented-by-list249453
Ref: Function sb-ext:package-implements-list249659
Ref: Function sb-ext:add-implementation-package249862
Ref: Function sb-ext:remove-implementation-package250131
Ref: Macro sb-ext:without-package-locks250421
Ref: Macro sb-ext:with-unlocked-packages250591
Node: Threading251708
Node: Threading basics252588
Ref: Structure sb-thread:thread252824
Ref: Variable sb-thread:*current-thread*253013
Ref: Function sb-thread:list-all-threads253103
Ref: Function sb-thread:thread-alive-p253342
Ref: Function sb-thread:thread-name253561
Ref: Function sb-thread:make-thread253833
Ref: Function sb-thread:thread-yield254087
Ref: Function sb-thread:join-thread254168
Ref: Function sb-thread:interrupt-thread254503
Ref: Function sb-thread:terminate-thread255253
Ref: Function sb-thread:symbol-value-in-thread255503
Ref: Condition sb-thread:thread-error256260
Ref: Function sb-thread:thread-error-thread256611
Ref: Condition sb-thread:interrupt-thread-error256736
Ref: Condition sb-thread:join-thread-error257061
Node: Special Variables257381
Node: Mutex Support258040
Ref: Structure sb-thread:mutex259063
Ref: Function sb-thread:make-mutex259170
Ref: Function sb-thread:mutex-name259244
Ref: Function sb-thread:mutex-value259424
Ref: Function sb-thread:get-mutex259586
Ref: Function sb-thread:release-mutex260522
Ref: Macro sb-thread:with-mutex261036
Ref: Macro sb-thread:with-recursive-lock261314
Node: Semaphores261652
Ref: Structure sb-thread:semaphore261889
Ref: Function sb-thread:make-semaphore262147
Ref: Function sb-thread:semaphore-count262265
Ref: Function sb-thread:semaphore-name262375
Ref: Function sb-thread:signal-semaphore262559
Ref: Function sb-thread:wait-on-semaphore262754
Node: Waitqueue/condition variables262940
Ref: Structure sb-thread:waitqueue265223
Ref: Function sb-thread:make-waitqueue265342
Ref: Function sb-thread:waitqueue-name265417
Ref: Function sb-thread:condition-wait265601
Ref: Function sb-thread:condition-notify265863
Ref: Function sb-thread:condition-broadcast266089
Node: Sessions/Debugging266184
Node: Foreign threads267635
Node: Implementation (Linux x86/x86-64)268746
Node: Timers271112
Ref: Structure sb-ext:timer272330
Ref: Function sb-ext:make-timer272512
Ref: Function sb-ext:timer-name273113
Ref: Function sb-ext:timer-scheduled-p273185
Ref: Function sb-ext:schedule-timer273387
Ref: Function sb-ext:unschedule-timer273788
Ref: Function sb-ext:list-all-timers273988
Node: Networking274074
Node: Sockets Overview274686
Node: General Sockets275749
Ref: Class sb-bsd-sockets:socket275900
Ref: Generic-Function sb-bsd-sockets:socket-bind276565
Ref: Generic-Function sb-bsd-sockets:socket-accept276874
Ref: Generic-Function sb-bsd-sockets:socket-connect277054
Ref: Generic-Function sb-bsd-sockets:socket-peername277233
Ref: Generic-Function sb-bsd-sockets:socket-name277396
Ref: Generic-Function sb-bsd-sockets:socket-receive277563
Ref: Generic-Function sb-bsd-sockets:socket-send278255
Ref: Generic-Function sb-bsd-sockets:socket-listen278926
Ref: Generic-Function sb-bsd-sockets:socket-open-p279222
Ref: Generic-Function sb-bsd-sockets:socket-close279344
Ref: Generic-Function sb-bsd-sockets:socket-make-stream279574
Ref: Method sb-bsd-sockets:socket-make-stream ((socket socket) &key input output (element-type 'character) (buffering full) (external-format default) timeout)280087
Ref: Function sb-bsd-sockets:socket-error280801
Ref: Generic-Function sb-bsd-sockets:non-blocking-mode280850
Node: Socket Options280952
Ref: Function sb-bsd-sockets:sockopt-reuse-address281434
Ref: Function sb-bsd-sockets:sockopt-keep-alive281608
Ref: Function sb-bsd-sockets:sockopt-oob-inline281779
Ref: Function sb-bsd-sockets:sockopt-bsd-compatible281950
Ref: Function sb-bsd-sockets:sockopt-pass-credentials282150
Ref: Function sb-bsd-sockets:sockopt-debug282351
Ref: Function sb-bsd-sockets:sockopt-dont-route282513
Ref: Function sb-bsd-sockets:sockopt-broadcast282684
Ref: Function sb-bsd-sockets:sockopt-tcp-nodelay282854
Node: INET Domain Sockets283025
Ref: Class sb-bsd-sockets:inet-socket283647
Ref: Function sb-bsd-sockets:make-inet-address283964
Ref: Function sb-bsd-sockets:get-protocol-by-name284163
Node: Local (Unix) Domain Sockets284378
Ref: Class sb-bsd-sockets:local-socket284899
Node: Name Service285108
Ref: Class sb-bsd-sockets:host-ent285591
Ref: Function sb-bsd-sockets:get-host-by-name286029
Ref: Function sb-bsd-sockets:get-host-by-address286338
Ref: Generic-Function sb-bsd-sockets:host-ent-address286590
Node: Profiling286702
Node: Deterministic Profiler287097
Ref: Macro sb-profile:profile287452
Ref: Macro sb-profile:unprofile288075
Ref: Function sb-profile:report288440
Ref: Function sb-profile:reset288719
Node: Statistical Profiler288803
Ref: Macro sb-sprof:with-profiling293889
Ref: Macro sb-sprof:with-sampling296252
Ref: Function sb-sprof:report296411
Ref: Function sb-sprof:reset298117
Ref: Function sb-sprof:start-profiling298172
Ref: Function sb-sprof:stop-profiling300061
Ref: Function sb-sprof:profile-call-counts300134
Ref: Function sb-sprof:unprofile-call-counts300544
Ref: Variable sb-sprof:*max-samples*300746
Ref: Variable sb-sprof:*sample-interval*300976
Node: Contributed Modules301197
Node: sb-aclrepl301716
Node: sb-grovel303311
Node: sb-posix312330
Ref: sb-posix-Footnote-1313414
Node: Lisp names for C names313565
Node: Types314718
Node: File-descriptors315390
Ref: Type sb-posix:file-descriptor315517
Ref: Type sb-posix:file-descriptor-designator315893
Ref: Function sb-posix:file-descriptor316090
Node: Filenames316215
Ref: Type sb-posix:filename316328
Ref: Type sb-posix:filename-designator317546
Ref: Function sb-posix:filename317743
Node: Function Parameters317840
Node: Function Return Values319061
Node: Lisp objects and C structures319858
Ref: Class sb-posix:flock321213
Ref: Class sb-posix:passwd322291
Ref: Class sb-posix:stat323766
Ref: Class sb-posix:termios325347
Ref: Class sb-posix:timeval326286
Node: Functions with idiosyncratic bindings326808
Ref: Function sb-posix:getcwd327109
Ref: Function sb-posix:readlink327231
Ref: Function sb-posix:syslog327361
Node: sb-md5327660
Ref: Function sb-md5:md5sum-file327866
Ref: Function sb-md5:md5sum-sequence327988
Ref: Function sb-md5:md5sum-stream328211
Ref: Function sb-md5:md5sum-string328373
Node: sb-queue329279
Ref: Structure sb-queue:queue329517
Ref: Function sb-queue:dequeue329763
Ref: Function sb-queue:enqueue329993
Ref: Function sb-queue:list-queue-contents330095
Ref: Function sb-queue:make-queue330295
Ref: Function sb-queue:queue-count330459
Ref: Function sb-queue:queue-empty-p330684
Ref: Function sb-queue:queue-name330783
Ref: Function sb-queue:queuep330962
Node: sb-rotate-byte331061
Ref: Function sb-rotate-byte:rotate-byte331649
Node: sb-cover331964
Ref: Function sb-cover:report333135
Ref: Function sb-cover:reset-coverage333887
Ref: Function sb-cover:clear-coverage333989
Ref: Function sb-cover:save-coverage334269
Ref: Function sb-cover:save-coverage-in-file334646
Ref: Function sb-cover:restore-coverage334812
Ref: Function sb-cover:restore-coverage-from-file334963
Node: Concept Index335133
Node: Function Index344290
Node: Variable Index375421
Node: Type Index378295
Node: Colophon385639

End Tag Table
