/usr/share/doc/sbcl-doc/html/sbcl.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 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. -->
<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
<head>
<title>SBCL User Manual</title>

<meta name="description" content="SBCL User Manual">
<meta name="keywords" content="SBCL User Manual">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="#Top" rel="start" title="Top">
<link href="#Concept-Index" rel="index" title="Concept Index">
<link href="#SEC_Contents" rel="contents" title="Table of Contents">
<link href="dir.html#Top" rel="up" title="(dir)">
<style type="text/css">
<!--
  

a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
.node { visibility:hidden; height: 0px; }
  .menu { visibility:hidden; height: 0px; }
  .chapter { background-color:#d0e4fe; }
  .section { background-color:#d0e4fe; }
  .subsection { background-color:#d0e4fe; }
  .settitle { background-color:#d0e4fe; }
  .contents { border: 2px solid black;
              margin: 1cm 1cm 1cm 1cm; 
              padding-left: 3mm; }
  body { padding-left: 3mm; }
-->
</style>


</head>

<body lang="en">
<h1 class="settitle" align="center">SBCL User Manual</h1>






<a name="SEC_Contents"></a>
<h2 class="contents-heading">Table of Contents</h2>

<div class="contents">

<ul class="no-bullet">
  <li><a name="toc-Getting-Support-and-Reporting-Bugs-1" href="#Getting-Support-and-Reporting-Bugs">1 Getting Support and Reporting Bugs</a>
  <ul class="no-bullet">
    <li><a name="toc-Volunteer-Support-1" href="#Volunteer-Support">1.1 Volunteer Support</a></li>
    <li><a name="toc-Commercial-Support-1" href="#Commercial-Support">1.2 Commercial Support</a></li>
    <li><a name="toc-Reporting-Bugs-1" href="#Reporting-Bugs">1.3 Reporting Bugs</a>
    <ul class="no-bullet">
      <li><a name="toc-How-to-Report-Bugs-Effectively" href="#How-to-Report-Bugs-Effectively">1.3.1 How to Report Bugs Effectively</a></li>
      <li><a name="toc-Signal-Related-Bugs" href="#Signal-Related-Bugs">1.3.2 Signal Related Bugs</a></li>
    </ul></li>
  </ul></li>
  <li><a name="toc-Introduction-1" href="#Introduction">2 Introduction</a>
  <ul class="no-bullet">
    <li><a name="toc-ANSI-Conformance-1" href="#ANSI-Conformance">2.1 ANSI Conformance</a></li>
    <li><a name="toc-Extensions-1" href="#Extensions">2.2 Extensions</a></li>
    <li><a name="toc-Idiosyncrasies-1" href="#Idiosyncrasies">2.3 Idiosyncrasies</a>
    <ul class="no-bullet">
      <li><a name="toc-Declarations-1" href="#Declarations">2.3.1 Declarations</a></li>
      <li><a name="toc-FASL-Format-1" href="#FASL-Format">2.3.2 FASL Format</a></li>
      <li><a name="toc-Compiler_002donly-Implementation-1" href="#Compiler_002donly-Implementation">2.3.3 Compiler-only Implementation</a></li>
      <li><a name="toc-Defining-Constants-1" href="#Defining-Constants">2.3.4 Defining Constants</a></li>
      <li><a name="toc-Style-Warnings-1" href="#Style-Warnings">2.3.5 Style Warnings</a></li>
    </ul></li>
    <li><a name="toc-Development-Tools-1" href="#Development-Tools">2.4 Development Tools</a>
    <ul class="no-bullet">
      <li><a name="toc-Editor-Integration-1" href="#Editor-Integration">2.4.1 Editor Integration</a></li>
      <li><a name="toc-Language-Reference-1" href="#Language-Reference">2.4.2 Language Reference</a></li>
      <li><a name="toc-Generating-Executables-1" href="#Generating-Executables">2.4.3 Generating Executables</a></li>
    </ul></li>
    <li><a name="toc-More-SBCL-Information-1" href="#More-SBCL-Information">2.5 More SBCL Information</a>
    <ul class="no-bullet">
      <li><a name="toc-SBCL-Homepage-1" href="#SBCL-Homepage">2.5.1 SBCL Homepage</a></li>
      <li><a name="toc-Online-Documentation-1" href="#Online-Documentation">2.5.2 Online Documentation</a></li>
      <li><a name="toc-Additional-Documentation-Files-1" href="#Additional-Documentation-Files">2.5.3 Additional Documentation Files</a></li>
      <li><a name="toc-Internals-Documentation-1" href="#Internals-Documentation">2.5.4 Internals Documentation</a></li>
    </ul></li>
    <li><a name="toc-More-Common-Lisp-Information-1" href="#More-Common-Lisp-Information">2.6 More Common Lisp Information</a>
    <ul class="no-bullet">
      <li><a name="toc-Internet-Community-1" href="#Internet-Community">2.6.1 Internet Community</a></li>
      <li><a name="toc-Third_002dparty-Libraries-1" href="#Third_002dparty-Libraries">2.6.2 Third-party Libraries</a></li>
      <li><a name="toc-Common-Lisp-Books-1" href="#Common-Lisp-Books">2.6.3 Common Lisp Books</a></li>
    </ul></li>
    <li><a name="toc-History-and-Implementation-of-SBCL-1" href="#History-and-Implementation-of-SBCL">2.7 History and Implementation of SBCL</a></li>
  </ul></li>
  <li><a name="toc-Starting-and-Stopping-1" href="#Starting-and-Stopping">3 Starting and Stopping</a>
  <ul class="no-bullet">
    <li><a name="toc-Starting-SBCL-1" href="#Starting-SBCL">3.1 Starting SBCL</a>
    <ul class="no-bullet">
      <li><a name="toc-From-Shell-to-Lisp" href="#Running-from-Shell">3.1.1 From Shell to Lisp</a></li>
      <li><a name="toc-Running-from-Emacs-1" href="#Running-from-Emacs">3.1.2 Running from Emacs</a></li>
      <li><a name="toc-Shebang-Scripts-1" href="#Shebang-Scripts">3.1.3 Shebang Scripts</a></li>
    </ul></li>
    <li><a name="toc-Stopping-SBCL-1" href="#Stopping-SBCL">3.2 Stopping SBCL</a>
    <ul class="no-bullet">
      <li><a name="toc-Exit-1" href="#Exit">3.2.1 Exit</a></li>
      <li><a name="toc-End-of-File-1" href="#End-of-File">3.2.2 End of File</a></li>
      <li><a name="toc-Saving-a-Core-Image-1" href="#Saving-a-Core-Image">3.2.3 Saving a Core Image</a></li>
      <li><a name="toc-Exit-on-Errors-1" href="#Exit-on-Errors">3.2.4 Exit on Errors</a></li>
    </ul></li>
    <li><a name="toc-Command-Line-Options-1" href="#Command-Line-Options">3.3 Command Line Options</a>
    <ul class="no-bullet">
      <li><a name="toc-Runtime-Options-1" href="#Runtime-Options">3.3.1 Runtime Options</a></li>
      <li><a name="toc-Toplevel-Options-1" href="#Toplevel-Options">3.3.2 Toplevel Options</a></li>
    </ul></li>
    <li><a name="toc-Initialization-Files-1" href="#Initialization-Files">3.4 Initialization Files</a></li>
    <li><a name="toc-Initialization-and-Exit-Hooks-1" href="#Initialization-and-Exit-Hooks">3.5 Initialization and Exit Hooks</a></li>
  </ul></li>
  <li><a name="toc-Compiler-1" href="#Compiler">4 Compiler</a>
  <ul class="no-bullet">
    <li><a name="toc-Diagnostic-Messages-1" href="#Diagnostic-Messages">4.1 Diagnostic Messages</a>
    <ul class="no-bullet">
      <li><a name="toc-Controlling-Verbosity-1" href="#Controlling-Verbosity">4.1.1 Controlling Verbosity</a></li>
      <li><a name="toc-Diagnostic-Severity-1" href="#Diagnostic-Severity">4.1.2 Diagnostic Severity</a></li>
      <li><a name="toc-Understanding-Compile-Diagnostics" href="#Understanding-Compiler-Diagnostics">4.1.3 Understanding Compile Diagnostics</a>
      <ul class="no-bullet">
        <li><a name="toc-The-Parts-of-a-Compiler-Diagnostic-1" href="#The-Parts-of-a-Compiler-Diagnostic">4.1.3.1 The Parts of a Compiler Diagnostic</a></li>
        <li><a name="toc-The-Original-and-Actual-Source-1" href="#The-Original-and-Actual-Source">4.1.3.2 The Original and Actual Source</a></li>
        <li><a name="toc-The-Processing-Path-1" href="#The-Processing-Path">4.1.3.3 The Processing Path</a></li>
      </ul></li>
    </ul></li>
    <li><a name="toc-Handling-of-Types-1" href="#Handling-of-Types">4.2 Handling of Types</a>
    <ul class="no-bullet">
      <li><a name="toc-Declarations-as-Assertions-1" href="#Declarations-as-Assertions">4.2.1 Declarations as Assertions</a></li>
      <li><a name="toc-Precise-Type-Checking-1" href="#Precise-Type-Checking">4.2.2 Precise Type Checking</a></li>
      <li><a name="toc-Getting-Existing-Programs-to-Run-1" href="#Getting-Existing-Programs-to-Run">4.2.3 Getting Existing Programs to Run</a></li>
      <li><a name="toc-Implementation-Limitations-1" href="#Implementation-Limitations">4.2.4 Implementation Limitations</a></li>
    </ul></li>
    <li><a name="toc-Compiler-Policy-1" href="#Compiler-Policy">4.3 Compiler Policy</a></li>
    <li><a name="toc-Compiler-Errors-1" href="#Compiler-Errors">4.4 Compiler Errors</a>
    <ul class="no-bullet">
      <li><a name="toc-Type-Errors-at-Compile-Time-1" href="#Type-Errors-at-Compile-Time">4.4.1 Type Errors at Compile Time</a></li>
      <li><a name="toc-Errors-During-Macroexpansion-1" href="#Errors-During-Macroexpansion">4.4.2 Errors During Macroexpansion</a></li>
      <li><a name="toc-Read-Errors-1" href="#Read-Errors">4.4.3 Read Errors</a></li>
    </ul></li>
    <li><a name="toc-Open-Coding-and-Inline-Expansion-1" href="#Open-Coding-and-Inline-Expansion">4.5 Open Coding and Inline Expansion</a></li>
    <li><a name="toc-Interpreter-1" href="#Interpreter">4.6 Interpreter</a></li>
  </ul></li>
  <li><a name="toc-Debugger-1" href="#Debugger">5 Debugger</a>
  <ul class="no-bullet">
    <li><a name="toc-Debugger-Entry-1" href="#Debugger-Entry">5.1 Debugger Entry</a>
    <ul class="no-bullet">
      <li><a name="toc-Debugger-Banner-1" href="#Debugger-Banner">5.1.1 Debugger Banner</a></li>
      <li><a name="toc-Debugger-Invocation-1" href="#Debugger-Invocation">5.1.2 Debugger Invocation</a></li>
    </ul></li>
    <li><a name="toc-Debugger-Command-Loop-1" href="#Debugger-Command-Loop">5.2 Debugger Command Loop</a></li>
    <li><a name="toc-Stack-Frames-1" href="#Stack-Frames">5.3 Stack Frames</a>
    <ul class="no-bullet">
      <li><a name="toc-Stack-Motion-1" href="#Stack-Motion">5.3.1 Stack Motion</a></li>
      <li><a name="toc-How-Arguments-are-Printed-1" href="#How-Arguments-are-Printed">5.3.2 How Arguments are Printed</a></li>
      <li><a name="toc-Function-Names-1" href="#Function-Names">5.3.3 Function Names</a>
      <ul class="no-bullet">
        <li><a name="toc-Entry-Point-Details-1" href="#Entry-Point-Details">5.3.3.1 Entry Point Details</a></li>
      </ul></li>
      <li><a name="toc-Debug-Tail-Recursion-1" href="#Debug-Tail-Recursion">5.3.4 Debug Tail Recursion</a></li>
      <li><a name="toc-Unknown-Locations-and-Interrupts-1" href="#Unknown-Locations-and-Interrupts">5.3.5 Unknown Locations and Interrupts</a></li>
    </ul></li>
    <li><a name="toc-Variable-Access-1" href="#Variable-Access">5.4 Variable Access</a>
    <ul class="no-bullet">
      <li><a name="toc-Variable-Value-Availability-1" href="#Variable-Value-Availability">5.4.1 Variable Value Availability</a></li>
      <li><a name="toc-Note-On-Lexical-Variable-Access-1" href="#Note-On-Lexical-Variable-Access">5.4.2 Note On Lexical Variable Access</a></li>
    </ul></li>
    <li><a name="toc-Source-Location-Printing-1" href="#Source-Location-Printing">5.5 Source Location Printing</a>
    <ul class="no-bullet">
      <li><a name="toc-How-the-Source-is-Found-1" href="#How-the-Source-is-Found">5.5.1 How the Source is Found</a></li>
      <li><a name="toc-Source-Location-Availability-1" href="#Source-Location-Availability">5.5.2 Source Location Availability</a></li>
    </ul></li>
    <li><a name="toc-Debugger-Policy-Control-1" href="#Debugger-Policy-Control">5.6 Debugger Policy Control</a></li>
    <li><a name="toc-Exiting-Commands-1" href="#Exiting-Commands">5.7 Exiting Commands</a></li>
    <li><a name="toc-Information-Commands-1" href="#Information-Commands">5.8 Information Commands</a></li>
    <li><a name="toc-Function-Tracing-1" href="#Function-Tracing">5.9 Function Tracing</a></li>
    <li><a name="toc-Single-Stepping-1" href="#Single-Stepping">5.10 Single Stepping</a></li>
    <li><a name="toc-Enabling-and-Disabling-the-Debugger-1" href="#Enabling-and-Disabling-the-Debugger">5.11 Enabling and Disabling the Debugger</a></li>
  </ul></li>
  <li><a name="toc-Efficiency-1" href="#Efficiency">6 Efficiency</a>
  <ul class="no-bullet">
    <li><a name="toc-Slot-access-1" href="#Slot-access">6.1 Slot access</a>
    <ul class="no-bullet">
      <li><a name="toc-Structure-object-slot-access" href="#Structure-object-slot-access">6.1.1 Structure object slot access</a></li>
      <li><a name="toc-Standard-object-slot-access" href="#Standard-object-slot-access">6.1.2 Standard object slot access</a></li>
    </ul></li>
    <li><a name="toc-Dynamic_002dextent-allocation-1" href="#Dynamic_002dextent-allocation">6.2 Dynamic-extent allocation</a></li>
    <li><a name="toc-Modular-arithmetic-1" href="#Modular-arithmetic">6.3 Modular arithmetic</a></li>
    <li><a name="toc-Global-and-Always_002dBound-variables-1" href="#Global-and-Always_002dBound-variables">6.4 Global and Always-Bound variables</a></li>
    <li><a name="toc-Miscellaneous-Efficiency-Issues-1" href="#Miscellaneous-Efficiency-Issues">6.5 Miscellaneous Efficiency Issues</a></li>
  </ul></li>
  <li><a name="toc-Beyond-the-ANSI-Standard-1" href="#Beyond-the-ANSI-Standard">7 Beyond the ANSI Standard</a>
  <ul class="no-bullet">
    <li><a name="toc-Reader-Extensions-1" href="#Reader-Extensions">7.1 Reader Extensions</a></li>
    <li><a name="toc-Package_002dLocal-Nicknames-1" href="#Package_002dLocal-Nicknames">7.2 Package-Local Nicknames</a></li>
    <li><a name="toc-Package-Variance-1" href="#Package-Variance">7.3 Package Variance</a></li>
    <li><a name="toc-Garbage-Collection-1" href="#Garbage-Collection">7.4 Garbage Collection</a>
    <ul class="no-bullet">
      <li><a name="toc-Finalization" href="#Finalization">7.4.1 Finalization</a></li>
      <li><a name="toc-Weak-Pointers" href="#Weak-Pointers">7.4.2 Weak Pointers</a></li>
      <li><a name="toc-Introspection-and-Tuning" href="#Introspection-and-Tuning">7.4.3 Introspection and Tuning</a></li>
    </ul></li>
    <li><a name="toc-Metaobject-Protocol-1" href="#Metaobject-Protocol">7.5 Metaobject Protocol</a>
    <ul class="no-bullet">
      <li><a name="toc-AMOP-Compatibility-of-Metaobject-Protocol" href="#AMOP-Compatibility-of-Metaobject-Protocol">7.5.1 AMOP Compatibility of Metaobject Protocol</a></li>
      <li><a name="toc-Metaobject-Protocol-Extensions" href="#Metaobject-Protocol-Extensions">7.5.2 Metaobject Protocol Extensions</a></li>
    </ul></li>
    <li><a name="toc-Extensible-Sequences-1" href="#Extensible-Sequences">7.6 Extensible Sequences</a>
    <ul class="no-bullet">
      <li><a name="toc-Iterator-Protocol-1" href="#Iterator-Protocol">7.6.1 Iterator Protocol</a></li>
      <li><a name="toc-Simple-Iterator-Protocol-1" href="#Simple-Iterator-Protocol">7.6.2 Simple Iterator Protocol</a></li>
    </ul></li>
    <li><a name="toc-Support-For-Unix-1" href="#Support-For-Unix">7.7 Support For Unix</a>
    <ul class="no-bullet">
      <li><a name="toc-Command_002dline-arguments-1" href="#Command_002dline-arguments">7.7.1 Command-line arguments</a></li>
      <li><a name="toc-Querying-the-process-environment-1" href="#Querying-the-process-environment">7.7.2 Querying the process environment</a></li>
      <li><a name="toc-Running-external-programs-1" href="#Running-external-programs">7.7.3 Running external programs</a></li>
    </ul></li>
    <li><a name="toc-Unicode-Support-1" href="#Unicode-Support">7.8 Unicode Support</a>
    <ul class="no-bullet">
      <li><a name="toc-Unicode-property-access" href="#Unicode-property-access">7.8.1 Unicode property access</a></li>
      <li><a name="toc-String-operations" href="#String-operations">7.8.2 String operations</a></li>
      <li><a name="toc-Breaking-strings" href="#Breaking-strings">7.8.3 Breaking strings</a></li>
    </ul></li>
    <li><a name="toc-Customization-Hooks-for-Users-1" href="#Customization-Hooks-for-Users">7.9 Customization Hooks for Users</a></li>
    <li><a name="toc-Tools-To-Help-Developers-1" href="#Tools-To-Help-Developers">7.10 Tools To Help Developers</a></li>
    <li><a name="toc-Resolution-of-Name-Conflicts-1" href="#Resolution-of-Name-Conflicts">7.11 Resolution of Name Conflicts</a></li>
    <li><a name="toc-Hash-Table-Extensions-1" href="#Hash-Table-Extensions">7.12 Hash Table Extensions</a></li>
    <li><a name="toc-Random-Number-Generation-1" href="#Random-Number-Generation">7.13 Random Number Generation</a></li>
    <li><a name="toc-Miscellaneous-Extensions-1" href="#Miscellaneous-Extensions">7.14 Miscellaneous Extensions</a></li>
    <li><a name="toc-Stale-Extensions-1" href="#Stale-Extensions">7.15 Stale Extensions</a></li>
    <li><a name="toc-Efficiency-Hacks-1" href="#Efficiency-Hacks">7.16 Efficiency Hacks</a></li>
  </ul></li>
  <li><a name="toc-Foreign-Function-Interface-1" href="#Foreign-Function-Interface">8 Foreign Function Interface</a>
  <ul class="no-bullet">
    <li><a name="toc-Introduction-to-the-Foreign-Function-Interface-1" href="#Introduction-to-the-Foreign-Function-Interface">8.1 Introduction to the Foreign Function Interface</a></li>
    <li><a name="toc-Foreign-Types-1" href="#Foreign-Types">8.2 Foreign Types</a>
    <ul class="no-bullet">
      <li><a name="toc-Defining-Foreign-Types-1" href="#Defining-Foreign-Types">8.2.1 Defining Foreign Types</a></li>
      <li><a name="toc-Foreign-Types-and-Lisp-Types-1" href="#Foreign-Types-and-Lisp-Types">8.2.2 Foreign Types and Lisp Types</a></li>
      <li><a name="toc-Foreign-Type-Specifiers-1" href="#Foreign-Type-Specifiers">8.2.3 Foreign Type Specifiers</a></li>
    </ul></li>
    <li><a name="toc-Operations-On-Foreign-Values-1" href="#Operations-On-Foreign-Values">8.3 Operations On Foreign Values</a>
    <ul class="no-bullet">
      <li><a name="toc-Accessing-Foreign-Values-1" href="#Accessing-Foreign-Values">8.3.1 Accessing Foreign Values</a>
      <ul class="no-bullet">
        <li><a name="toc-Untyped-memory" href="#Untyped-memory">8.3.1.1 Untyped memory</a></li>
      </ul></li>
      <li><a name="toc-Coercing-Foreign-Values-1" href="#Coercing-Foreign-Values">8.3.2 Coercing Foreign Values</a></li>
      <li><a name="toc-Foreign-Dynamic-Allocation-1" href="#Foreign-Dynamic-Allocation">8.3.3 Foreign Dynamic Allocation</a></li>
    </ul></li>
    <li><a name="toc-Foreign-Variables-1" href="#Foreign-Variables">8.4 Foreign Variables</a>
    <ul class="no-bullet">
      <li><a name="toc-Local-Foreign-Variables-1" href="#Local-Foreign-Variables">8.4.1 Local Foreign Variables</a></li>
      <li><a name="toc-External-Foreign-Variables-1" href="#External-Foreign-Variables">8.4.2 External Foreign Variables</a></li>
    </ul></li>
    <li><a name="toc-Foreign-Data-Structure-Examples-1" href="#Foreign-Data-Structure-Examples">8.5 Foreign Data Structure Examples</a></li>
    <li><a name="toc-Loading-Shared-Object-Files-1" href="#Loading-Shared-Object-Files">8.6 Loading Shared Object Files</a></li>
    <li><a name="toc-Foreign-Function-Calls-1" href="#Foreign-Function-Calls">8.7 Foreign Function Calls</a>
    <ul class="no-bullet">
      <li><a name="toc-The-alien_002dfuncall-Primitive-1" href="#The-alien_002dfuncall-Primitive">8.7.1 The <code>alien-funcall</code> Primitive</a></li>
      <li><a name="toc-The-define_002dalien_002droutine-Macro-1" href="#The-define_002dalien_002droutine-Macro">8.7.2 The <code>define-alien-routine</code> Macro</a></li>
      <li><a name="toc-define_002dalien_002droutine-Example-1" href="#define_002dalien_002droutine-Example">8.7.3 <code>define-alien-routine</code> Example</a></li>
      <li><a name="toc-Calling-Lisp-From-C-1" href="#Calling-Lisp-From-C">8.7.4 Calling Lisp From C</a></li>
    </ul></li>
    <li><a name="toc-Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface-1" href="#Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface">8.8 Step-By-Step Example of the Foreign Function Interface</a></li>
  </ul></li>
  <li><a name="toc-Pathnames-1" href="#Pathnames">9 Pathnames</a>
  <ul class="no-bullet">
    <li><a name="toc-Lisp-Pathnames-1" href="#Lisp-Pathnames">9.1 Lisp Pathnames</a>
    <ul class="no-bullet">
      <li><a name="toc-Home-Directory-Specifiers" href="#Home-Directory-Specifiers">9.1.1 Home Directory Specifiers</a></li>
      <li><a name="toc-The-SYS-Logical-Pathname-Host" href="#The-SYS-Logical-Pathname-Host">9.1.2 The SYS Logical Pathname Host</a></li>
    </ul></li>
    <li><a name="toc-Native-Filenames-1" href="#Native-Filenames">9.2 Native Filenames</a></li>
  </ul></li>
  <li><a name="toc-Streams-1" href="#Streams">10 Streams</a>
  <ul class="no-bullet">
    <li><a name="toc-External-Formats-1" href="#External-Formats">10.1 External Formats</a></li>
    <li><a name="toc-Bivalent-Streams-1" href="#Bivalent-Streams">10.2 Bivalent Streams</a></li>
    <li><a name="toc-Gray-Streams-1" href="#Gray-Streams">10.3 Gray Streams</a>
    <ul class="no-bullet">
      <li><a name="toc-Gray-Streams-classes-1" href="#Gray-Streams-classes">10.3.1 Gray Streams classes</a></li>
      <li><a name="toc-Methods-common-to-all-streams-1" href="#Methods-common-to-all-streams">10.3.2 Methods common to all streams</a></li>
      <li><a name="toc-Input-stream-methods-1" href="#Input-stream-methods">10.3.3 Input stream methods</a></li>
      <li><a name="toc-Character-input-stream-methods-1" href="#Character-input-stream-methods">10.3.4 Character input stream methods</a></li>
      <li><a name="toc-Output-stream-methods-1" href="#Output-stream-methods">10.3.5 Output stream methods</a></li>
      <li><a name="toc-Character-output-stream-methods-1" href="#Character-output-stream-methods">10.3.6 Character output stream methods</a></li>
      <li><a name="toc-Binary-stream-methods-1" href="#Binary-stream-methods">10.3.7 Binary stream methods</a></li>
      <li><a name="toc-Gray-Streams-examples-1" href="#Gray-Streams-examples">10.3.8 Gray Streams examples</a>
      <ul class="no-bullet">
        <li><a name="toc-Character-counting-input-stream-1" href="#Character-counting-input-stream">10.3.8.1 Character counting input stream</a></li>
        <li><a name="toc-Output-prefixing-character-stream-1" href="#Output-prefixing-character-stream">10.3.8.2 Output prefixing character stream</a></li>
      </ul></li>
    </ul></li>
    <li><a name="toc-Simple-Streams-1" href="#Simple-Streams">10.4 Simple Streams</a></li>
  </ul></li>
  <li><a name="toc-Package-Locks-1" href="#Package-Locks">11 Package Locks</a>
  <ul class="no-bullet">
    <li><a name="toc-Package-Lock-Concepts-1" href="#Package-Lock-Concepts">11.1 Package Lock Concepts</a>
    <ul class="no-bullet">
      <li><a name="toc-Package-Locking-Overview" href="#Package-Lock-Overview">11.1.1 Package Locking Overview</a></li>
      <li><a name="toc-Implementation-Packages-1" href="#Implementation-Packages">11.1.2 Implementation Packages</a></li>
      <li><a name="toc-Package-Lock-Violations-1" href="#Package-Lock-Violations">11.1.3 Package Lock Violations</a>
      <ul class="no-bullet">
        <li><a name="toc-Lexical-Bindings-and-Declarations" href="#Lexical-Bindings-and-Declarations">11.1.3.1 Lexical Bindings and Declarations</a></li>
        <li><a name="toc-Other-Operations" href="#Other-Operations">11.1.3.2 Other Operations</a></li>
      </ul></li>
      <li><a name="toc-Package-Locks-in-Compiled-Code-1" href="#Package-Locks-in-Compiled-Code">11.1.4 Package Locks in Compiled Code</a>
      <ul class="no-bullet">
        <li><a name="toc-Interned-Symbols" href="#Interned-Symbols">11.1.4.1 Interned Symbols</a></li>
        <li><a name="toc-Other-Limitations-on-Compiled-Code" href="#Other-Limitations-on-Compiled-Code">11.1.4.2 Other Limitations on Compiled Code</a></li>
      </ul></li>
      <li><a name="toc-Operations-Violating-Package-Locks-1" href="#Operations-Violating-Package-Locks">11.1.5 Operations Violating Package Locks</a>
      <ul class="no-bullet">
        <li><a name="toc-Operations-on-Packages" href="#Operations-on-Packages">11.1.5.1 Operations on Packages</a></li>
        <li><a name="toc-Operations-on-Symbols" href="#Operations-on-Symbols">11.1.5.2 Operations on Symbols</a></li>
      </ul></li>
    </ul></li>
    <li><a name="toc-Package-Lock-Dictionary-1" href="#Package-Lock-Dictionary">11.2 Package Lock Dictionary</a></li>
  </ul></li>
  <li><a name="toc-Threading-1" href="#Threading">12 Threading</a>
  <ul class="no-bullet">
    <li><a name="toc-Threading-basics-1" href="#Threading-basics">12.1 Threading basics</a>
    <ul class="no-bullet">
      <li><a name="toc-Thread-Objects" href="#Thread-Objects">12.1.1 Thread Objects</a></li>
      <li><a name="toc-Making_002c-Returning-From_002c-Joining_002c-and-Yielding-Threads" href="#Making_002c-Returning-From_002c-Joining_002c-and-Yielding-Threads">12.1.2 Making, Returning From, Joining, and Yielding Threads</a></li>
      <li><a name="toc-Asynchronous-Operations" href="#Asynchronous-Operations">12.1.3 Asynchronous Operations</a></li>
      <li><a name="toc-Miscellaneous-Operations" href="#Miscellaneous-Operations">12.1.4 Miscellaneous Operations</a></li>
      <li><a name="toc-Error-Conditions" href="#Error-Conditions">12.1.5 Error Conditions</a></li>
    </ul></li>
    <li><a name="toc-Special-Variables-1" href="#Special-Variables">12.2 Special Variables</a></li>
    <li><a name="toc-Atomic-Operations-1" href="#Atomic-Operations">12.3 Atomic Operations</a>
    <ul class="no-bullet">
      <li><a name="toc-CAS-Protocol" href="#CAS-Protocol">CAS Protocol</a></li>
    </ul></li>
    <li><a name="toc-Mutex-Support-1" href="#Mutex-Support">12.4 Mutex Support</a></li>
    <li><a name="toc-Semaphores-1" href="#Semaphores">12.5 Semaphores</a></li>
    <li><a name="toc-Waitqueue_002fcondition-variables-1" href="#Waitqueue_002fcondition-variables">12.6 Waitqueue/condition variables</a></li>
    <li><a name="toc-Barriers-1" href="#Barriers">12.7 Barriers</a></li>
    <li><a name="toc-Sessions_002fDebugging-1" href="#Sessions_002fDebugging">12.8 Sessions/Debugging</a></li>
    <li><a name="toc-Foreign-threads-1" href="#Foreign-threads">12.9 Foreign threads</a></li>
    <li><a name="toc-Implementation-_0028Linux-x86_002fx86_002d64_0029-1" href="#Implementation-_0028Linux-x86_002fx86_002d64_0029">12.10 Implementation (Linux x86/x86-64)</a></li>
  </ul></li>
  <li><a name="toc-Timers-1" href="#Timers">13 Timers</a>
  <ul class="no-bullet">
    <li><a name="toc-Timer-Dictionary" href="#Timer-Dictionary">13.1 Timer Dictionary</a></li>
  </ul></li>
  <li><a name="toc-Networking-1" href="#Networking">14 Networking</a>
  <ul class="no-bullet">
    <li><a name="toc-Sockets-Overview-1" href="#Sockets-Overview">14.1 Sockets Overview</a></li>
    <li><a name="toc-General-Sockets-1" href="#General-Sockets">14.2 General Sockets</a></li>
    <li><a name="toc-Socket-Options-1" href="#Socket-Options">14.3 Socket Options</a></li>
    <li><a name="toc-INET-Domain-Sockets-1" href="#INET-Domain-Sockets">14.4 INET Domain Sockets</a></li>
    <li><a name="toc-Local-_0028Unix_0029-Domain-Sockets-1" href="#Local-_0028Unix_0029-Domain-Sockets">14.5 Local (Unix) Domain Sockets</a></li>
    <li><a name="toc-Name-Service-1" href="#Name-Service">14.6 Name Service</a></li>
  </ul></li>
  <li><a name="toc-Profiling-1" href="#Profiling">15 Profiling</a>
  <ul class="no-bullet">
    <li><a name="toc-Deterministic-Profiler-1" href="#Deterministic-Profiler">15.1 Deterministic Profiler</a></li>
    <li><a name="toc-Statistical-Profiler-1" href="#Statistical-Profiler">15.2 Statistical Profiler</a>
    <ul class="no-bullet">
      <li><a name="toc-Example-Usage" href="#Example-Usage">15.2.1 Example Usage</a></li>
      <li><a name="toc-Output" href="#Output">15.2.2 Output</a></li>
      <li><a name="toc-Platform-support" href="#Platform-support">15.2.3 Platform support</a></li>
      <li><a name="toc-Macros" href="#Macros">15.2.4 Macros</a></li>
      <li><a name="toc-Functions" href="#Functions">15.2.5 Functions</a></li>
      <li><a name="toc-Variables" href="#Variables">15.2.6 Variables</a></li>
      <li><a name="toc-Credits" href="#Credits">15.2.7 Credits</a></li>
    </ul></li>
  </ul></li>
  <li><a name="toc-Contributed-Modules-1" href="#Contributed-Modules">16 Contributed Modules</a>
  <ul class="no-bullet">
    <li><a name="toc-sb_002daclrepl-1" href="#sb_002daclrepl">16.1 sb-aclrepl</a>
    <ul class="no-bullet">
      <li><a name="toc-Usage" href="#Usage">16.1.1 Usage</a></li>
      <li><a name="toc-Example-Initialization" href="#Example-Initialization">16.1.2 Example Initialization</a></li>
      <li><a name="toc-Credits-1" href="#Credits-1">16.1.3 Credits</a></li>
    </ul></li>
    <li><a name="toc-sb_002dconcurrency-1" href="#sb_002dconcurrency">16.2 sb-concurrency</a>
    <ul class="no-bullet">
      <li><a name="toc-Queue" href="#Queue">16.2.1 Queue</a></li>
      <li><a name="toc-Mailbox-_0028lock_002dfree_0029" href="#Mailbox-_0028lock_002dfree_0029">16.2.2 Mailbox (lock-free)</a></li>
      <li><a name="toc-Gates" href="#Gates">16.2.3 Gates</a></li>
      <li><a name="toc-Frlocks_002c-aka-Fast-Read-Locks" href="#Frlocks_002c-aka-Fast-Read-Locks">16.2.4 Frlocks, aka Fast Read Locks</a></li>
    </ul></li>
    <li><a name="toc-sb_002dcover-1" href="#sb_002dcover">16.3 sb-cover</a>
    <ul class="no-bullet">
      <li><a name="toc-Example-Usage-1" href="#Example-Usage-1">16.3.1 Example Usage</a></li>
      <li><a name="toc-Functions-1" href="#Functions-1">16.3.2 Functions</a></li>
    </ul></li>
    <li><a name="toc-sb_002dgrovel-1" href="#sb_002dgrovel">16.4 sb-grovel</a>
    <ul class="no-bullet">
      <li><a name="toc-Using-sb_002dgrovel-in-your-own-ASDF-system" href="#Using-sb_002dgrovel-in-your-own-ASDF-system">16.4.1 Using sb-grovel in your own ASDF system</a></li>
      <li><a name="toc-Contents-of-a-grovel_002dconstants_002dfile" href="#Contents-of-a-grovel_002dconstants_002dfile">16.4.2 Contents of a grovel-constants-file</a></li>
      <li><a name="toc-Programming-with-sb_002dgrovel_0027s-structure-types" href="#Programming-with-sb_002dgrovel_0027s-structure-types">16.4.3 Programming with sb-grovel&rsquo;s structure types</a>
      <ul class="no-bullet">
        <li><a name="toc-Traps-and-Pitfalls" href="#Traps-and-Pitfalls">16.4.3.1 Traps and Pitfalls</a></li>
      </ul></li>
    </ul></li>
    <li><a name="toc-sb_002dmd5-1" href="#sb_002dmd5">16.5 sb-md5</a>
    <ul class="no-bullet">
      <li><a name="toc-Credits-2" href="#Credits-2">16.5.1 Credits</a></li>
    </ul></li>
    <li><a name="toc-sb_002dposix-1" href="#sb_002dposix">16.6 sb-posix</a>
    <ul class="no-bullet">
      <li><a name="toc-Lisp-names-for-C-names-1" href="#Lisp-names-for-C-names">16.6.1 Lisp names for C names</a></li>
      <li><a name="toc-Types-1" href="#Types">16.6.2 Types</a>
      <ul class="no-bullet">
        <li><a name="toc-File_002ddescriptors-1" href="#File_002ddescriptors">16.6.2.1 File-descriptors</a></li>
        <li><a name="toc-Filenames-1" href="#Filenames">16.6.2.2 Filenames</a></li>
      </ul></li>
      <li><a name="toc-Function-Parameters-1" href="#Function-Parameters">16.6.3 Function Parameters</a></li>
      <li><a name="toc-Function-Return-Values-1" href="#Function-Return-Values">16.6.4 Function Return Values</a></li>
      <li><a name="toc-Lisp-objects-and-C-structures-1" href="#Lisp-objects-and-C-structures">16.6.5 Lisp objects and C structures</a></li>
      <li><a name="toc-Functions-with-idiosyncratic-bindings-1" href="#Functions-with-idiosyncratic-bindings">16.6.6 Functions with idiosyncratic bindings</a></li>
    </ul></li>
    <li><a name="toc-sb_002dqueue-1" href="#sb_002dqueue">16.7 sb-queue</a></li>
    <li><a name="toc-sb_002drotate_002dbyte-1" href="#sb_002drotate_002dbyte">16.8 sb-rotate-byte</a></li>
  </ul></li>
  <li><a name="toc-Deprecation-1" href="#Deprecation">17 Deprecation</a>
  <ul class="no-bullet">
    <li><a name="toc-Why-Deprecate_003f-1" href="#Why-Deprecate_003f">17.1 Why Deprecate?</a></li>
    <li><a name="toc-The-Deprecation-Pipeline-1" href="#The-Deprecation-Pipeline">17.2 The Deprecation Pipeline</a></li>
    <li><a name="toc-Deprecation-Conditions-1" href="#Deprecation-Conditions">17.3 Deprecation Conditions</a></li>
    <li><a name="toc-Introspecting-Deprecation-Information-1" href="#Introspecting-Deprecation-Information">17.4 Introspecting Deprecation Information</a></li>
    <li><a name="toc-Deprecation-Declaration-1" href="#Deprecation-Declaration">17.5 Deprecation Declaration</a></li>
    <li><a name="toc-Deprecation-Examples-1" href="#Deprecation-Examples">17.6 Deprecation Examples</a></li>
    <li><a name="toc-Deprecated-Interfaces-in-SBCL-1" href="#Deprecated-Interfaces-in-SBCL">17.7 Deprecated Interfaces in SBCL</a>
    <ul class="no-bullet">
      <li><a name="toc-List-of-Deprecated-Interfaces" href="#List-of-Deprecated-Interfaces">17.7.1 List of Deprecated Interfaces</a>
      <ul class="no-bullet">
        <li><a name="toc-Early-Deprecation" href="#Early-Deprecation">17.7.1.1 Early Deprecation</a></li>
        <li><a name="toc-Late-Deprecation" href="#Late-Deprecation">17.7.1.2 Late Deprecation</a></li>
        <li><a name="toc-Final-Deprecation" href="#Final-Deprecation">17.7.1.3 Final Deprecation</a></li>
      </ul></li>
      <li><a name="toc-Historical-Interfaces" href="#Historical-Interfaces">17.7.2 Historical Interfaces</a></li>
    </ul></li>
  </ul></li>
  <li><a name="toc-Concept-Index-1" href="#Concept-Index">Appendix A Concept Index</a></li>
  <li><a name="toc-Function-Index-1" href="#Function-Index">Appendix B Function Index</a></li>
  <li><a name="toc-Variable-Index-1" href="#Variable-Index">Appendix C Variable Index</a></li>
  <li><a name="toc-Type-Index-1" href="#Type-Index">Appendix D Type Index</a></li>
  <li><a name="toc-Colophon-1" href="#Colophon">Colophon</a></li>
</ul>
</div>





<a name="Top"></a>
<div class="header">
<p>
Next: <a href="#Getting-Support-and-Reporting-Bugs" accesskey="n" rel="next">Getting Support and Reporting Bugs</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sbcl"></a>
<h1 class="top">sbcl</h1>

<blockquote>
<p>This manual is part of the SBCL software system. See the
<samp>README</samp> file for more information.
</p>
<p>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 <samp>COPYING</samp> and
<samp>CREDITS</samp> files for more information.
</p></blockquote>


<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Getting-Support-and-Reporting-Bugs" accesskey="1">Getting Support and Reporting Bugs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="2">Introduction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Starting-and-Stopping" accesskey="3">Starting and Stopping</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Compiler" accesskey="4">Compiler</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Debugger" accesskey="5">Debugger</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Efficiency" accesskey="6">Efficiency</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Beyond-the-ANSI-Standard" accesskey="7">Beyond the ANSI Standard</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Function-Interface" accesskey="8">Foreign Function Interface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Pathnames" accesskey="9">Pathnames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Streams">Streams</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package-Locks">Package Locks</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Threading">Threading</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Timers">Timers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Networking">Networking</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Profiling">Profiling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Contributed-Modules">Contributed Modules</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Deprecation">Deprecation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Concept-Index">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Function-Index">Function Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Variable-Index">Variable Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Type-Index">Type Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Colophon">Colophon</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>


<hr>
<a name="Getting-Support-and-Reporting-Bugs"></a>
<div class="header">
<p>
Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Getting-Support-and-Reporting-Bugs-1"></a>
<h2 class="chapter">1 Getting Support and Reporting Bugs</h2>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Volunteer-Support" accesskey="1">Volunteer Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Commercial-Support" accesskey="2">Commercial Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Reporting-Bugs" accesskey="3">Reporting Bugs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Volunteer-Support"></a>
<div class="header">
<p>
Next: <a href="#Commercial-Support" accesskey="n" rel="next">Commercial Support</a>, Up: <a href="#Getting-Support-and-Reporting-Bugs" accesskey="u" rel="up">Getting Support and Reporting Bugs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Volunteer-Support-1"></a>
<h3 class="section">1.1 Volunteer Support</h3>

<p>Your primary source of SBCL support should probably be the mailing
list <strong>sbcl-help</strong>: in addition to other users SBCL developers
monitor this list and are available for advice. As an anti-spam
measure subscription is required for posting:
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="https://lists.sourceforge.net/lists/listinfo/sbcl-help">https://lists.sourceforge.net/lists/listinfo/sbcl-help</a>
</p>
<p>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.
</p>
<p>Before sending mail, check the list archives at either
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="http://sourceforge.net/mailarchive/forum.php?forum_name=sbcl-help">http://sourceforge.net/mailarchive/forum.php?forum_name=sbcl-help</a>
</p>
<p>or
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="http://news.gmane.org/gmane.lisp.steel-bank.general">http://news.gmane.org/gmane.lisp.steel-bank.general</a>
</p>
<p>to see if your question has been answered already. Checking the bug
database is also worth it See <a href="#Reporting-Bugs">Reporting Bugs</a>, to see if the issue
is already known.
</p>
<p>For general advice on asking good questions, see
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="http://www.catb.org/~esr/faqs/smart-questions.html">http://www.catb.org/~esr/faqs/smart-questions.html</a>.
</p>
<hr>
<a name="Commercial-Support"></a>
<div class="header">
<p>
Next: <a href="#Reporting-Bugs" accesskey="n" rel="next">Reporting Bugs</a>, Previous: <a href="#Volunteer-Support" accesskey="p" rel="prev">Volunteer Support</a>, Up: <a href="#Getting-Support-and-Reporting-Bugs" accesskey="u" rel="up">Getting Support and Reporting Bugs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Commercial-Support-1"></a>
<h3 class="section">1.2 Commercial Support</h3>

<p>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.
</p>
<p>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.
</p>
<p>(At present, no companies or consultants wish to advertise paid support
or custom SBCL development in this manual).
</p>
<hr>
<a name="Reporting-Bugs"></a>
<div class="header">
<p>
Previous: <a href="#Commercial-Support" accesskey="p" rel="prev">Commercial Support</a>, Up: <a href="#Getting-Support-and-Reporting-Bugs" accesskey="u" rel="up">Getting Support and Reporting Bugs</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reporting-Bugs-1"></a>
<h3 class="section">1.3 Reporting Bugs</h3>

<p>SBCL uses Launchpad to track bugs. The bug database is available at
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="https://bugs.launchpad.net/sbcl">https://bugs.launchpad.net/sbcl</a>
</p>
<p>Reporting bugs there requires registering at Launchpad. However, bugs
can also be reported on the mailing list <strong>sbcl-bugs</strong>, which is
moderated but does <em>not</em> require subscribing.
</p>
<p>Simply send email to <a href="mailto:sbcl-bugs@lists.sourceforge.net">sbcl-bugs@lists.sourceforge.net</a> and the
bug will be checked and added to Launchpad by SBCL maintainers.
</p>
<a name="How-to-Report-Bugs-Effectively"></a>
<h4 class="subsection">1.3.1 How to Report Bugs Effectively</h4>

<p>Please include enough information in a bug report that someone reading
it can reproduce the problem, i.e. don&rsquo;t write
</p>
<div class="example">
<pre class="example">Subject: apparent bug in PRINT-OBJECT (or *PRINT-LENGTH*?)
PRINT-OBJECT doesn't seem to work with *PRINT-LENGTH*. Is this a bug?
</pre></div>

<p>but instead
</p>
<div class="example">
<pre class="example">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.
</pre></div>

<p>A more in-depth discussion on reporting bugs effectively can be found
at
</p>
<p>&nbsp;<!-- /@w --> &nbsp;<!-- /@w --> <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">http://www.chiark.greenend.org.uk/~sgtatham/bugs.html</a>.
</p>
<a name="Signal-Related-Bugs"></a>
<h4 class="subsection">1.3.2 Signal Related Bugs</h4>

<p>If you run into a signal related bug, you are getting fatal errors
such as <code>signal N is [un]blocked</code> or just hangs, and you want to
send a useful bug report then:
</p>
<ol>
<li> <a name="index-ldb"></a>
Compile SBCL with ldb support (feature <code>:sb-ldb</code>, see
<samp>base-target-features.lisp-expr</samp>) and change <code>#define QSHOW_SIGNAL 0</code> to
<code>#define QSHOW_SIGNAL 1</code> in <samp>src/runtime/runtime.h</samp>.

</li><li> Isolate a smallish test case, run it.

</li><li> If it just hangs kill it with sigabrt: <code>kill -ABRT &lt;pidof sbcl&gt;</code>.

</li><li> Print the backtrace from ldb by typing <code>ba</code>.

</li><li> Attach gdb: <code>gdb -p &lt;pidof sbcl&gt;</code> and get backtraces for all threads:
<code>thread apply all ba</code>.

</li><li> If multiple threads are in play then still in gdb, try to get Lisp
backtrace for all threads: <code>thread apply all call
backtrace_from_fp($ebp, 100)</code>. Substitute <code>$ebp</code> with <code>$rbp</code>
on x86-64. The backtraces will appear in the stdout of the SBCL
process.

</li><li> Send a report with the backtraces and the output (both stdout and
stderr) produced by SBCL.

</li><li> Don&rsquo;t forget to include OS and SBCL version.

</li><li> If available, include information on outcome of the same test with
other versions of SBCL, OS, ...
</li></ol>
<hr>
<a name="Introduction"></a>
<div class="header">
<p>
Next: <a href="#Starting-and-Stopping" accesskey="n" rel="next">Starting and Stopping</a>, Previous: <a href="#Getting-Support-and-Reporting-Bugs" accesskey="p" rel="prev">Getting Support and Reporting Bugs</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Introduction-1"></a>
<h2 class="chapter">2 Introduction</h2>

<p>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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#ANSI-Conformance" accesskey="1">ANSI Conformance</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Extensions" accesskey="2">Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Idiosyncrasies" accesskey="3">Idiosyncrasies</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Development-Tools" accesskey="4">Development Tools</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#More-SBCL-Information" accesskey="5">More SBCL Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#More-Common-Lisp-Information" accesskey="6">More Common Lisp Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#History-and-Implementation-of-SBCL" accesskey="7">History and Implementation of SBCL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>



<hr>
<a name="ANSI-Conformance"></a>
<div class="header">
<p>
Next: <a href="#Extensions" accesskey="n" rel="next">Extensions</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="ANSI-Conformance-1"></a>
<h3 class="section">2.1 ANSI Conformance</h3>

<p>Essentially every type of non-conformance is considered a bug. (The
exceptions involve internal inconsistencies in the standard.)
See <a href="#Reporting-Bugs">Reporting Bugs</a>.
</p>
<hr>
<a name="Extensions"></a>
<div class="header">
<p>
Next: <a href="#Idiosyncrasies" accesskey="n" rel="next">Idiosyncrasies</a>, Previous: <a href="#ANSI-Conformance" accesskey="p" rel="prev">ANSI Conformance</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Extensions-1"></a>
<h3 class="section">2.2 Extensions</h3>

<p>SBCL comes with numerous extensions, some in core and some in modules
loadable with <code>require</code>. Unfortunately, not all of these
extensions have proper documentation yet.
</p>

<dl compact="compact">
<dt><strong>System Definition Tool</strong></dt>
<dd><p><code>asdf</code> is a flexible and popular protocol-oriented system
definition tool by Daniel Barlow. See <a href="asdf.html#Top">(asdf)the asdf manual</a>, for
more information.
</p>
</dd>
<dt><strong>Foreign Function Interface</strong></dt>
<dd><p><code>sb-alien</code> package allows interfacing with C-code, loading shared
object files, etc. See <a href="#Foreign-Function-Interface">Foreign Function Interface</a>.
</p>
<p><code>sb-grovel</code> can be used to partially automate generation of
foreign function interface definitions. See <a href="#sb_002dgrovel">sb-grovel</a>.
</p>
</dd>
<dt><strong>Recursive Event Loop</strong></dt>
<dd><p>SBCL provides a recursive event loop (<code>serve-event</code>) for doing
non-blocking IO on multiple streams without using threads.
</p>
</dd>
<dt><strong>Metaobject Protocol</strong></dt>
<dd><p><code>sb-mop</code> package provides a metaobject protocol for the Common
Lisp Object System as described in <cite>Art of Metaobject Protocol</cite>.
</p>
</dd>
<dt><strong>Extensible Sequences</strong></dt>
<dd><p>SBCL allows users to define subclasses of the <code>sequence</code>
class. See <a href="#Extensible-Sequences">Extensible Sequences</a>.
</p>
</dd>
<dt><strong>Native Threads</strong></dt>
<dd><p>SBCL has native threads on x86/Linux, capable of taking advantage
of SMP on multiprocessor machines. See <a href="#Threading">Threading</a>.
</p>
</dd>
<dt><strong>Network Interface</strong></dt>
<dd><p><code>sb-bsd-sockets</code> is a low-level networking interface, providing
both TCP and UDP sockets. See <a href="#Networking">Networking</a>.
</p>
</dd>
<dt><strong>Introspective Facilities</strong></dt>
<dd><p><code>sb-introspect</code> module offers numerous introspective extensions,
including access to function lambda-lists and a cross referencing
facility.
</p>
</dd>
<dt><strong>Operating System Interface</strong></dt>
<dd><p><code>sb-ext</code> contains a number of functions for running external
processes, accessing environment variables, etc.
</p>
<p><code>sb-posix</code> module provides a lispy interface to standard POSIX
facilities.
</p>
</dd>
<dt><strong>Extensible Streams</strong></dt>
<dd><p><code>sb-gray</code> is an implementation of <em>Gray Streams</em>. See <a href="#Gray-Streams">Gray Streams</a>.
</p>
<p><code>sb-simple-streams</code> is an implementation of the <em>simple
streams</em> API proposed by Franz Inc. See <a href="#Simple-Streams">Simple Streams</a>.
</p>
</dd>
<dt><strong>Profiling</strong></dt>
<dd><p><code>sb-profile</code> is a exact per-function profiler. See <a href="#Deterministic-Profiler">Deterministic Profiler</a>.
</p>
<p><code>sb-sprof</code> is a statistical profiler, capable of call-graph
generation and instruction level profiling, which also supports
allocation profiling. See <a href="#Statistical-Profiler">Statistical Profiler</a>.
</p>
</dd>
<dt><strong>Customization Hooks</strong></dt>
<dd><p>SBCL contains a number of extra-standard customization hooks that
can be used to tweak the behaviour of the system. See <a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a>.
</p>
<p><code>sb-aclrepl</code> provides an Allegro CL -style toplevel for SBCL,
as an alternative to the classic CMUCL-style one. See <a href="#sb_002daclrepl">sb-aclrepl</a>.
</p>
</dd>
<dt><strong>CLTL2 Compatibility Layer</strong></dt>
<dd><p><code>sb-cltl2</code> module provides <code>compiler-let</code> and environment
access functionality described in <cite>Common Lisp The Language, 2nd
Edition</cite> which were removed from the language during the ANSI
standardization process.
</p>
</dd>
<dt><strong>Executable Delivery</strong></dt>
<dd><p>The <code>:executable</code> argument to <a href="#Function-sb_002dext_003asave_002dlisp_002dand_002ddie">Function sb-ext:save-lisp-and-die</a> can produce a &lsquo;standalone&rsquo; executable
containing both an image of the current Lisp session and an SBCL
runtime.
</p>
</dd>
<dt><strong>Bitwise Rotation</strong></dt>
<dd><p><code>sb-rotate-byte</code> provides an efficient primitive for bitwise
rotation of integers, an operation required by e.g. numerous
cryptographic algorithms, but not available as a primitive in ANSI
Common Lisp. See <a href="#sb_002drotate_002dbyte">sb-rotate-byte</a>.
</p>
</dd>
<dt><strong>Test Harness</strong></dt>
<dd><p><code>sb-rt</code> module is a simple yet attractive regression and
unit-test framework.
</p>
</dd>
<dt><strong>MD5 Sums</strong></dt>
<dd><p><code>sb-md5</code> is an implementation of the MD5 message digest algorithm
for Common Lisp, using the modular arithmetic optimizations provided
by SBCL. See <a href="#sb_002dmd5">sb-md5</a>.
</p>
</dd>
</dl>




<hr>
<a name="Idiosyncrasies"></a>
<div class="header">
<p>
Next: <a href="#Development-Tools" accesskey="n" rel="next">Development Tools</a>, Previous: <a href="#Extensions" accesskey="p" rel="prev">Extensions</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Idiosyncrasies-1"></a>
<h3 class="section">2.3 Idiosyncrasies</h3>

<p>The information in this section describes some of the ways that SBCL
deals with choices that the ANSI standard leaves to the
implementation.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Declarations" accesskey="1">Declarations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#FASL-Format" accesskey="2">FASL Format</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Compiler_002donly-Implementation" accesskey="3">Compiler-only Implementation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Defining-Constants" accesskey="4">Defining Constants</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Style-Warnings" accesskey="5">Style Warnings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Declarations"></a>
<div class="header">
<p>
Next: <a href="#FASL-Format" accesskey="n" rel="next">FASL Format</a>, Up: <a href="#Idiosyncrasies" accesskey="u" rel="up">Idiosyncrasies</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Declarations-1"></a>
<h4 class="subsection">2.3.1 Declarations</h4>

<p>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
<a href="#Declarations-as-Assertions">Declarations as Assertions</a>.
</p>

<hr>
<a name="FASL-Format"></a>
<div class="header">
<p>
Next: <a href="#Compiler_002donly-Implementation" accesskey="n" rel="next">Compiler-only Implementation</a>, Previous: <a href="#Declarations" accesskey="p" rel="prev">Declarations</a>, Up: <a href="#Idiosyncrasies" accesskey="u" rel="up">Idiosyncrasies</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="FASL-Format-1"></a>
<h4 class="subsection">2.3.2 FASL Format</h4>

<p>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.
</p>
<p>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 (see <a href="#Initialization-Files">Initialization Files</a>.)
</p>
<div class="lisp">
<pre class="lisp">(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))))
</pre></div>


<hr>
<a name="Compiler_002donly-Implementation"></a>
<div class="header">
<p>
Next: <a href="#Defining-Constants" accesskey="n" rel="next">Defining Constants</a>, Previous: <a href="#FASL-Format" accesskey="p" rel="prev">FASL Format</a>, Up: <a href="#Idiosyncrasies" accesskey="u" rel="up">Idiosyncrasies</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Compiler_002donly-Implementation-1"></a>
<h4 class="subsection">2.3.3 Compiler-only Implementation</h4>

<p>SBCL is essentially a compiler-only implementation of Common Lisp.
That is, for all but a few special cases, <code>eval</code> creates a lambda
expression, calls <code>compile</code> on the lambda expression to create a
compiled function, and then calls <code>funcall</code> on the resulting
function object. A more traditional interpreter is also available on
default builds; it is usually only called internally.  This is
explicitly allowed by the ANSI standard, but leads to some oddities;
e.g. at default settings, <code>functionp</code> and
<code>compiled-function-p</code> are equivalent, and they collapse into the
same function when SBCL is built without the interpreter.
</p>
<hr>
<a name="Defining-Constants"></a>
<div class="header">
<p>
Next: <a href="#Style-Warnings" accesskey="n" rel="next">Style Warnings</a>, Previous: <a href="#Compiler_002donly-Implementation" accesskey="p" rel="prev">Compiler-only Implementation</a>, Up: <a href="#Idiosyncrasies" accesskey="u" rel="up">Idiosyncrasies</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Defining-Constants-1"></a>
<h4 class="subsection">2.3.4 Defining Constants</h4>
<a name="index-defconstant-_005bcl_005d"></a>

<p>SBCL is quite strict about ANSI&rsquo;s definition of <code>defconstant</code>.
ANSI says that doing <code>defconstant</code> of the same symbol more than
once is undefined unless the new value is <code>eql</code> to the old value.
Conforming to this specification is a nuisance when the &ldquo;constant&rdquo;
value is only constant under some weaker test like <code>string=</code> or
<code>equal</code>.
</p>
<p>It&rsquo;s especially annoying because, in SBCL, <code>defconstant</code> takes
effect not only at load time but also at compile time, so that just
compiling and loading reasonable code like
</p><div class="lisp">
<pre class="lisp">(defconstant +foobyte+ '(1 4))
</pre></div>
<p>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.
</p>
<p>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 <code>defconstant</code> either with
<code>defparameter</code> or with a customized macro which does the right
thing, e.g.
</p><div class="lisp">
<pre class="lisp">(defmacro define-constant (name value &amp;optional doc)
  `(defconstant ,name (if (boundp ',name) (symbol-value ',name) ,value)
                      ,@(when doc (list doc))))
</pre></div>
<p>or possibly along the lines of the <code>defconstant-eqx</code> macro used
internally in the implementation of SBCL itself. In circumstances
where this is not appropriate, the programmer can handle the condition
type <code>sb-ext:defconstant-uneql</code>, and choose either the
<code>continue</code> or <code>abort</code> restart as appropriate.
</p>
<hr>
<a name="Style-Warnings"></a>
<div class="header">
<p>
Previous: <a href="#Defining-Constants" accesskey="p" rel="prev">Defining Constants</a>, Up: <a href="#Idiosyncrasies" accesskey="u" rel="up">Idiosyncrasies</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Style-Warnings-1"></a>
<h4 class="subsection">2.3.5 Style Warnings</h4>

<p>SBCL gives style warnings about various kinds of perfectly legal code,
e.g.
</p>
<ul>
<li> <code>defmethod</code> without a preceding <code>defgeneric</code>;

</li><li> multiple <code>defun</code>s of the same symbol in different units;

</li><li> special variables not named in the conventional <code>*foo*</code> style,
and lexical variables unconventionally named in the <code>*foo*</code> style

</li></ul>

<p>This causes friction with people who point out that other ways of
organizing code (especially avoiding the use of <code>defgeneric</code>) are
just as aesthetically stylish.  However, these warnings should be read
not as &ldquo;warning, bad aesthetics detected, you have no style&rdquo; but
&ldquo;warning, this style keeps the compiler from understanding the code
as well as you might like.&rdquo; That is, unless the compiler warns about
such conditions, there&rsquo;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 <code>defun</code>s is pointlessly annoying
when you compile and then load a function containing <code>defun</code>
wrapped in <code>eval-when</code>, and ideally should be suppressed in that
case, but still isn&rsquo;t as of SBCL 0.7.6.)
</p>



<hr>
<a name="Development-Tools"></a>
<div class="header">
<p>
Next: <a href="#More-SBCL-Information" accesskey="n" rel="next">More SBCL Information</a>, Previous: <a href="#Idiosyncrasies" accesskey="p" rel="prev">Idiosyncrasies</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Development-Tools-1"></a>
<h3 class="section">2.4 Development Tools</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Editor-Integration" accesskey="1">Editor Integration</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Language-Reference" accesskey="2">Language Reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Generating-Executables" accesskey="3">Generating Executables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Editor-Integration"></a>
<div class="header">
<p>
Next: <a href="#Language-Reference" accesskey="n" rel="next">Language Reference</a>, Up: <a href="#Development-Tools" accesskey="u" rel="up">Development Tools</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Editor-Integration-1"></a>
<h4 class="subsection">2.4.1 Editor Integration</h4>

<p>Though SBCL can be used running &ldquo;bare&rdquo;, 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.
</p>
<p>Currently <em>SLIME</em><a name="DOCF1" href="#FOOT1"><sup>1</sup></a> (Superior Lisp Interaction
Mode for Emacs) together with Emacs is recommended for use with
SBCL, though other options exist as well.
</p>
<p>SLIME can be downloaded from
<a href="http://www.common-lisp.net/project/slime/">http://www.common-lisp.net/project/slime/</a>.
</p>
<hr>
<a name="Language-Reference"></a>
<div class="header">
<p>
Next: <a href="#Generating-Executables" accesskey="n" rel="next">Generating Executables</a>, Previous: <a href="#Editor-Integration" accesskey="p" rel="prev">Editor Integration</a>, Up: <a href="#Development-Tools" accesskey="u" rel="up">Development Tools</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Language-Reference-1"></a>
<h4 class="subsection">2.4.2 Language Reference</h4>

<p><em>CLHS</em> (Common Lisp Hyperspec) is a hypertext version of the ANSI
standard, made freely available by <em>LispWorks</em> &ndash; an invaluable
reference.
</p>
<p>See: <a href="http://www.lispworks.com/reference/HyperSpec/index.html">http://www.lispworks.com/reference/HyperSpec/index.html</a>
</p>
<hr>
<a name="Generating-Executables"></a>
<div class="header">
<p>
Previous: <a href="#Language-Reference" accesskey="p" rel="prev">Language Reference</a>, Up: <a href="#Development-Tools" accesskey="u" rel="up">Development Tools</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Generating-Executables-1"></a>
<h4 class="subsection">2.4.3 Generating Executables</h4>

<p>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
<code>compile</code> and <code>load</code>, which requires the compiler to be present
in the executable.  For further information, See <a href="#Function-sb_002dext_003asave_002dlisp_002dand_002ddie">Function sb-ext:save-lisp-and-die</a>.
</p>

<hr>
<a name="More-SBCL-Information"></a>
<div class="header">
<p>
Next: <a href="#More-Common-Lisp-Information" accesskey="n" rel="next">More Common Lisp Information</a>, Previous: <a href="#Development-Tools" accesskey="p" rel="prev">Development Tools</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="More-SBCL-Information-1"></a>
<h3 class="section">2.5 More SBCL Information</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#SBCL-Homepage" accesskey="1">SBCL Homepage</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Online-Documentation" accesskey="2">Online Documentation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Additional-Documentation-Files" accesskey="3">Additional Documentation Files</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Internals-Documentation" accesskey="4">Internals Documentation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="SBCL-Homepage"></a>
<div class="header">
<p>
Next: <a href="#Online-Documentation" accesskey="n" rel="next">Online Documentation</a>, Up: <a href="#More-SBCL-Information" accesskey="u" rel="up">More SBCL Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="SBCL-Homepage-1"></a>
<h4 class="subsection">2.5.1 SBCL Homepage</h4>

<p>The SBCL website at <a href="http://www.sbcl.org/">http://www.sbcl.org/</a> has some general
information, plus links to mailing lists devoted to SBCL, and to
archives of these mailing lists. Subscribing to the mailing lists
<cite>sbcl-help</cite> and <cite>sbcl-announce</cite> is recommended: both are
fairly low-volume, and help you keep abreast with SBCL development.
</p>
<hr>
<a name="Online-Documentation"></a>
<div class="header">
<p>
Next: <a href="#Additional-Documentation-Files" accesskey="n" rel="next">Additional Documentation Files</a>, Previous: <a href="#SBCL-Homepage" accesskey="p" rel="prev">SBCL Homepage</a>, Up: <a href="#More-SBCL-Information" accesskey="u" rel="up">More SBCL Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Online-Documentation-1"></a>
<h4 class="subsection">2.5.2 Online Documentation</h4>

<p>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 <code>inspect</code>) are documented in text available by typing
<code>help</code> at their command prompts. The extensions for functions
which don&rsquo;t have their own command prompt (such as <code>trace</code>) 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.
</p>
<hr>
<a name="Additional-Documentation-Files"></a>
<div class="header">
<p>
Next: <a href="#Internals-Documentation" accesskey="n" rel="next">Internals Documentation</a>, Previous: <a href="#Online-Documentation" accesskey="p" rel="prev">Online Documentation</a>, Up: <a href="#More-SBCL-Information" accesskey="u" rel="up">More SBCL Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Additional-Documentation-Files-1"></a>
<h4 class="subsection">2.5.3 Additional Documentation Files</h4>

<p>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 on your system, e.g. in
<samp>/usr/local/share/doc/sbcl/</samp>.
</p>
<dl compact="compact">
<dt><samp>COPYING</samp></dt>
<dd><p>Licence and copyright summary.
</p>
</dd>
<dt><samp>CREDITS</samp></dt>
<dd><p>Authorship information on various parts of SBCL.
</p>
</dd>
<dt><samp>INSTALL</samp></dt>
<dd><p>Covers installing SBCL from both source and binary distributions on
your system, and also has some installation related troubleshooting
information.
</p>
</dd>
<dt><samp>NEWS</samp></dt>
<dd><p>Summarizes changes between various SBCL versions.
</p>
</dd>
</dl>

<hr>
<a name="Internals-Documentation"></a>
<div class="header">
<p>
Previous: <a href="#Additional-Documentation-Files" accesskey="p" rel="prev">Additional Documentation Files</a>, Up: <a href="#More-SBCL-Information" accesskey="u" rel="up">More SBCL Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Internals-Documentation-1"></a>
<h4 class="subsection">2.5.4 Internals Documentation</h4>

<p>If you&rsquo;re interested in the development of the SBCL system itself,
then subscribing to <cite>sbcl-devel</cite> is a good idea.
</p>
<p>SBCL internals documentation &ndash; besides comments in the source &ndash; is
currently maintained as a <em>wiki-like</em> website:
<a href="http://sbcl-internals.cliki.net/">http://sbcl-internals.cliki.net/</a>.
</p>
<p>Some low-level information describing the programming details of the
conversion from CMUCL to SBCL is available in the
<samp>doc/FOR-CMUCL-DEVELOPERS</samp> file in the SBCL distribution, though
it is not installed by default.
</p>
<hr>
<a name="More-Common-Lisp-Information"></a>
<div class="header">
<p>
Next: <a href="#History-and-Implementation-of-SBCL" accesskey="n" rel="next">History and Implementation of SBCL</a>, Previous: <a href="#More-SBCL-Information" accesskey="p" rel="prev">More SBCL Information</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="More-Common-Lisp-Information-1"></a>
<h3 class="section">2.6 More Common Lisp Information</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Internet-Community" accesskey="1">Internet Community</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Third_002dparty-Libraries" accesskey="2">Third-party Libraries</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Common-Lisp-Books" accesskey="3">Common Lisp Books</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Internet-Community"></a>
<div class="header">
<p>
Next: <a href="#Third_002dparty-Libraries" accesskey="n" rel="next">Third-party Libraries</a>, Up: <a href="#More-Common-Lisp-Information" accesskey="u" rel="up">More Common Lisp Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Internet-Community-1"></a>
<h4 class="subsection">2.6.1 Internet Community</h4>


<p>The Common Lisp internet community is fairly diverse:
<a href="news://comp.lang.lisp">news://comp.lang.lisp</a> 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.
<a href="http://www.lisp.org">http://www.lisp.org</a> and <a href="http://www.cliki.net">http://www.cliki.net</a> contain
numerous pointers places in the net where lispers talks shop.
</p>
<hr>
<a name="Third_002dparty-Libraries"></a>
<div class="header">
<p>
Next: <a href="#Common-Lisp-Books" accesskey="n" rel="next">Common Lisp Books</a>, Previous: <a href="#Internet-Community" accesskey="p" rel="prev">Internet Community</a>, Up: <a href="#More-Common-Lisp-Information" accesskey="u" rel="up">More Common Lisp Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Third_002dparty-Libraries-1"></a>
<h4 class="subsection">2.6.2 Third-party Libraries</h4>

<p>For a wealth of information about free Common Lisp libraries and tools
we recommend checking out <em>CLiki</em>: <a href="http://www.cliki.net/">http://www.cliki.net/</a>.
</p>
<hr>
<a name="Common-Lisp-Books"></a>
<div class="header">
<p>
Previous: <a href="#Third_002dparty-Libraries" accesskey="p" rel="prev">Third-party Libraries</a>, Up: <a href="#More-Common-Lisp-Information" accesskey="u" rel="up">More Common Lisp Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Common-Lisp-Books-1"></a>
<h4 class="subsection">2.6.3 Common Lisp Books</h4>

<p>If you&rsquo;re not a programmer and you&rsquo;re trying to learn, many
introductory Lisp books are available. However, we don&rsquo;t have any
standout favorites. If you can&rsquo;t decide, try checking the Usenet
<a href="news://comp.lang.lisp">news://comp.lang.lisp</a> FAQ for recent recommendations.
</p>

<p>If you are an experienced programmer in other languages but need to
learn about Common Lisp, some books stand out:
</p>
<dl compact="compact">
<dt><cite>Practical Common Lisp, by Peter Seibel</cite></dt>
<dd><p>An excellent introduction to the language, covering both the basics
and &ldquo;advanced topics&rdquo; like macros, CLOS, and packages. Available
both in print format and on the web: <a href="http://www.gigamonkeys.com/book/">http://www.gigamonkeys.com/book/</a>.
</p>
</dd>
<dt><cite>Paradigms Of Artificial Intelligence Programming, by Peter Norvig</cite></dt>
<dd><p>Good information on general Common Lisp programming, and many
nontrivial examples. Whether or not your work is AI, it&rsquo;s a very good
book to look at.
</p>
</dd>
<dt><cite>On Lisp, by Paul Graham</cite></dt>
<dd><p>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&rsquo;t really even
try to cover the language as a whole, focusing solely on macros.
Downloadable from <a href="http://www.paulgraham.com/onlisp.html">http://www.paulgraham.com/onlisp.html</a>.
</p>
</dd>
<dt><cite>Object-Oriented Programming In Common Lisp, by Sonya Keene</cite></dt>
<dd><p>With the exception of <cite>Practical Common Lisp</cite> most introductory
books don&rsquo;t emphasize CLOS. This one does. Even if you&rsquo;re very
knowledgeable about object oriented programming in the abstract, it&rsquo;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&rsquo;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.
</p>
</dd>
<dt><cite>Art Of Metaobject Programming, by Gregor Kiczales et al.</cite></dt>
<dd><p>Currently the prime source of information on the Common Lisp Metaobject
Protocol, which is supported by SBCL. Section 2 (Chapters 5 and 6) are
freely available at <a href="http://www.lisp.org/mop/">http://www.lisp.org/mop/</a>.
</p>
</dd>
</dl>




<hr>
<a name="History-and-Implementation-of-SBCL"></a>
<div class="header">
<p>
Previous: <a href="#More-Common-Lisp-Information" accesskey="p" rel="prev">More Common Lisp Information</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="History-and-Implementation-of-SBCL-1"></a>
<h3 class="section">2.7 History and Implementation of SBCL</h3>

<p>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.
</p>
<p>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:
</p>
<ul>
<li> 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.

</li><li> 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.

</li><li> The system is implemented as a C program which is responsible for
supplying low-level services and loading a Lisp <samp>.core</samp>
file.

</li></ul>

<a name="index-Garbage-Collection_002c-generational"></a>
<p>SBCL also inherited some newer architectural features from CMUCL. The
most important is that on some architectures it has a generational
garbage collector (&ldquo;GC&rdquo;), which has various implications (mostly
good) for performance. These are discussed in another chapter,
<a href="#Efficiency">Efficiency</a>.
</p>
<p>SBCL has diverged from CMUCL in that SBCL is now essentially a
&ldquo;compiler-only implementation&rdquo; of Common Lisp. This is a change in
implementation strategy, taking advantage of the freedom &ldquo;any of these
facilities might share the same execution strategy&rdquo; guaranteed in the
ANSI specification section 3.1 (&ldquo;Evaluation&rdquo;). It does not mean SBCL
can&rsquo;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 <code>compiled-function-p</code>; and it is visible in the
way that SBCL doesn&rsquo;t have many bugs which behave differently in
interpreted code than in compiled code.) What it means is that in SBCL,
the <code>eval</code> function only truly &ldquo;interprets&rdquo; a few easy kinds of
forms, such as symbols which are <code>boundp</code>. More complicated forms
are evaluated by calling <code>compile</code> and then calling <code>funcall</code>
on the returned result.
</p>
<p>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.
</p>
<a name="index-Garbage-Collection_002c-conservative"></a>
<p>On the x86 SBCL &ndash; like the x86 port of CMUCL &ndash; uses a
<em>conservative</em> GC. This means that it doesn&rsquo;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.
</p>
<p>The fork from CMUCL was based on a major rewrite of the system
bootstrap process. CMUCL has for many years tolerated a very unusual
&ldquo;build&rdquo; procedure which doesn&rsquo;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 &ndash; it&rsquo;s easy to accidentally &ldquo;build&rdquo; a CMUCL system
containing characteristics not reflected in the current version of the
source code.
</p>
<p>Other major changes since the fork from CMUCL include
</p>
<ul>
<li> 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.

</li><li> 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.

</li></ul>
<hr>
<a name="Starting-and-Stopping"></a>
<div class="header">
<p>
Next: <a href="#Compiler" accesskey="n" rel="next">Compiler</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Starting-and-Stopping-1"></a>
<h2 class="chapter">3 Starting and Stopping</h2>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Starting-SBCL" accesskey="1">Starting SBCL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Stopping-SBCL" accesskey="2">Stopping SBCL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Command-Line-Options" accesskey="3">Command Line Options</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Initialization-Files" accesskey="4">Initialization Files</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Initialization-and-Exit-Hooks" accesskey="5">Initialization and Exit Hooks</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Starting-SBCL"></a>
<div class="header">
<p>
Next: <a href="#Stopping-SBCL" accesskey="n" rel="next">Stopping SBCL</a>, Up: <a href="#Starting-and-Stopping" accesskey="u" rel="up">Starting and Stopping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Starting-SBCL-1"></a>
<h3 class="section">3.1 Starting SBCL</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Running-from-Shell" accesskey="1">Running from Shell</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Running-from-Emacs" accesskey="2">Running from Emacs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Shebang-Scripts" accesskey="3">Shebang Scripts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Running-from-Shell"></a>
<div class="header">
<p>
Next: <a href="#Running-from-Emacs" accesskey="n" rel="next">Running from Emacs</a>, Up: <a href="#Starting-SBCL" accesskey="u" rel="up">Starting SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="From-Shell-to-Lisp"></a>
<h4 class="subsection">3.1.1 From Shell to Lisp</h4>

<p>To run SBCL type <code>sbcl</code> at the command line.
</p>
<p>You should end up in the toplevel <em>REPL</em> (read, eval, print
-loop), where you can interact with SBCL by typing expressions.
</p>
<div class="smallexample">
<pre class="smallexample">$ sbcl
This is SBCL 0.8.13.60, an implementation of ANSI Common Lisp.
More information about SBCL is available at &lt;http://www.sbcl.org/&gt;.

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
* (exit)
$
</pre></div>

<p>See also <a href="#Command-Line-Options">Command Line Options</a> and <a href="#Stopping-SBCL">Stopping SBCL</a>.
</p>
<hr>
<a name="Running-from-Emacs"></a>
<div class="header">
<p>
Next: <a href="#Shebang-Scripts" accesskey="n" rel="next">Shebang Scripts</a>, Previous: <a href="#Running-from-Shell" accesskey="p" rel="prev">Running from Shell</a>, Up: <a href="#Starting-SBCL" accesskey="u" rel="up">Starting SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Running-from-Emacs-1"></a>
<h4 class="subsection">3.1.2 Running from Emacs</h4>

<p>To run SBCL as an inferior-lisp from Emacs in your <samp>.emacs</samp> do
something like:
</p>
<div class="lisp">
<pre class="lisp">;;; The SBCL binary and command-line arguments
(setq inferior-lisp-program &quot;/usr/local/bin/sbcl --noinform&quot;)
</pre></div>

<p>For more information on using SBCL with Emacs, see <a href="#Editor-Integration">Editor Integration</a>.
</p>

<hr>
<a name="Shebang-Scripts"></a>
<div class="header">
<p>
Previous: <a href="#Running-from-Emacs" accesskey="p" rel="prev">Running from Emacs</a>, Up: <a href="#Starting-SBCL" accesskey="u" rel="up">Starting SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Shebang-Scripts-1"></a>
<h4 class="subsection">3.1.3 Shebang Scripts</h4>
<a name="index-_002aposix_002dargv_002a-_005bsb_002dext_005d"></a>

<p>Standard Unix tools that are interpreters follow a common command line
protocol that is necessary to work with &ldquo;shebang scripts&rdquo;. SBCL supports
this via the <code>--script</code> command line option.
</p>
<p>Example file (<samp>hello.lisp</samp>):
</p>
<div class="lisp">
<pre class="lisp">#!/usr/local/bin/sbcl --script
(write-line &quot;Hello, World!&quot;)
</pre></div>

<p>Usage examples:
</p>
<div class="smallexample">
<pre class="smallexample">$ ./hello.lisp
Hello, World!
</pre></div>

<div class="smallexample">
<pre class="smallexample">$ sbcl --script hello.lisp
Hello, World!
</pre></div>

<hr>
<a name="Stopping-SBCL"></a>
<div class="header">
<p>
Next: <a href="#Command-Line-Options" accesskey="n" rel="next">Command Line Options</a>, Previous: <a href="#Starting-SBCL" accesskey="p" rel="prev">Starting SBCL</a>, Up: <a href="#Starting-and-Stopping" accesskey="u" rel="up">Starting and Stopping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Stopping-SBCL-1"></a>
<h3 class="section">3.2 Stopping SBCL</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Exit" accesskey="1">Exit</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#End-of-File" accesskey="2">End of File</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Saving-a-Core-Image" accesskey="3">Saving a Core Image</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Exit-on-Errors" accesskey="4">Exit on Errors</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Exit"></a>
<div class="header">
<p>
Next: <a href="#End-of-File" accesskey="n" rel="next">End of File</a>, Up: <a href="#Stopping-SBCL" accesskey="u" rel="up">Stopping SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Exit-1"></a>
<h4 class="subsection">3.2.1 Exit</h4>

<p>SBCL can be stopped at any time by calling <code>sb-ext:exit</code>,
optionally returning a specified numeric value to the calling process.
See <a href="#Threading">Threading</a> for information about terminating individual threads.
</p>
<a name="Function-sb_002dext_003aexit"></a><dl>
<dt><a name="index-exit"></a>Function: <strong>exit</strong> <em>[sb-ext] &amp;key code abort timeout</em></dt>
<dd><p>Terminates the process, causing <code>sbcl</code> to exit with <code>code</code>. <code>code</code>
defaults to 0 when <code>abort</code> is false, and 1 when it is true.
</p>
<p>When <code>abort</code> is false (the default), current thread is first unwound,
<code>*exit-hooks*</code> are run, other threads are terminated, and standard
output streams are flushed before <code>sbcl</code> calls exit(3) <code>--</code> at which point
atexit(3) functions will run. If multiple threads call <code>exit</code> with <code>abort</code>
being false, the first one to call it will complete the protocol.
</p>
<p>When <code>abort</code> is true, <code>sbcl</code> exits immediately by calling _exit(2) without
unwinding stack, or calling exit hooks. Note that _exit(2) does not
call atexit(3) functions unlike exit(3).
</p>
<p>Recursive calls to <code>exit</code> cause <code>exit</code> to behave as it <code>abort</code> was true.
</p>
<p><code>timeout</code> controls waiting for other threads to terminate when <code>abort</code> is
<code>nil</code>. Once current thread has been unwound and <code>*exit-hooks*</code> have been
run, spawning new threads is prevented and all other threads are
terminated by calling <code>terminate-thread</code> on them. The system then waits
for them to finish using <code>join-thread</code>, waiting at most a total <code>timeout</code>
seconds for all threads to join. Those threads that do not finish
in time are simply ignored while the exit protocol continues. <code>timeout</code>
defaults to <code>*exit-timeout*</code>, which in turn defaults to 60. <code>timeout</code> <code>nil</code>
means to wait indefinitely.
</p>
<p>Note that <code>timeout</code> applies only to <code>join-thread</code>, not <code>*exit-hooks*</code>. Since
<code>terminate-thread</code> is asynchronous, getting multithreaded application
termination with complex cleanups right using it can be tricky. To
perform an orderly synchronous shutdown use an exit hook instead of
relying on implicit thread termination.
</p>
<p>Consequences are unspecified if serious conditions occur during <code>exit</code>
excepting errors from <code>*exit-hooks*</code>, which cause warnings and stop
execution of the hook that signaled, but otherwise allow the exit
process to continue normally.
</p></dd></dl>

<hr>
<a name="End-of-File"></a>
<div class="header">
<p>
Next: <a href="#Saving-a-Core-Image" accesskey="n" rel="next">Saving a Core Image</a>, Previous: <a href="#Exit" accesskey="p" rel="prev">Exit</a>, Up: <a href="#Stopping-SBCL" accesskey="u" rel="up">Stopping SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="End-of-File-1"></a>
<h4 class="subsection">3.2.2 End of File</h4>

<p>By default SBCL also exits on end of input, caused either by user
pressing <kbd>Control-D</kbd> on an attached terminal, or end of input when
using SBCL as part of a shell pipeline.
</p>
<hr>
<a name="Saving-a-Core-Image"></a>
<div class="header">
<p>
Next: <a href="#Exit-on-Errors" accesskey="n" rel="next">Exit on Errors</a>, Previous: <a href="#End-of-File" accesskey="p" rel="prev">End of File</a>, Up: <a href="#Stopping-SBCL" accesskey="u" rel="up">Stopping SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Saving-a-Core-Image-1"></a>
<h4 class="subsection">3.2.3 Saving a Core Image</h4>

<p>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.
</p>
<a name="Function-sb_002dext_003asave_002dlisp_002dand_002ddie"></a><dl>
<dt><a name="index-save_002dlisp_002dand_002ddie"></a>Function: <strong>save-lisp-and-die</strong> <em>[sb-ext] core-file-name &amp;key toplevel executable save-runtime-options purify root-structures environment-name compression</em></dt>
<dd><p>Save a &quot;core image&quot;, 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.
</p>
<p>The following <code>&amp;key</code> arguments are defined:
</p>

<dl compact="compact">
<dt><em><code>:toplevel</code></em></dt>
<dd><p>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 <code>(sb-ext:exit :code 0) </code>being called.
</p>
<p><code>toplevel</code> functions should always provide an <code>abort</code> restart: otherwise
     code they call will run without one.
</p>

</dd>
<dt><em><code>:executable</code></em></dt>
<dd><p>If true, arrange to combine the <code>sbcl</code> 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 &ndash;noinform runtime option.
</p>

</dd>
<dt><em><code>:save-runtime-options</code></em></dt>
<dd><p>If true, values of runtime options &ndash;dynamic-space-size and
     &ndash;control-stack-size that were used to start <code>sbcl</code> 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 <code>:executable</code> is <code>nil</code>.
</p>

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

</dd>
<dt><em><code>:root-structures</code></em></dt>
<dd><p>This should be a list of the main entry points in any newly loaded
     systems. This need not be supplied, but locality and/or <code>gc</code> performance
     may be better if they are. This has two different but related meanings:
     If <code>:purify</code> is true <code>-</code> and only for cheneygc <code>-</code> the root structures
     are those which anchor the set of objects moved into static space.
     On gencgc <code>-</code> and only on platforms supporting immobile code <code>-</code> these are
     the functions and/or function-names which commence a depth-first scan
     of code when reordering based on the statically observable call chain.
     The complete set of reachable objects is not affected per se.
     This argument is meaningless if neither enabling precondition holds.
</p>

</dd>
<dt><em><code>:environment-name</code></em></dt>
<dd><p>This has no purpose; it is accepted only for legacy compatibility.
</p>

</dd>
<dt><em><code>:compression</code></em></dt>
<dd><p>This is only meaningful if the runtime was built with the <code>:sb-core-compression</code>
     feature enabled. If <code>nil</code> (the default), saves to uncompressed core files. If
     <code>:sb-core-compression</code> was enabled at build-time, the argument may also be
     an integer from -1 to 9, corresponding to zlib compression levels, or <code>t</code>
     (which is equivalent to the default compression level, -1).
</p>

</dd>
<dt><em><code>:application-type</code></em></dt>
<dd><p>Present only on Windows and is meaningful only with <code>:executable</code> <code>t</code>.
     Specifies the subsystem of the executable, <code>:console</code> or <code>:gui</code>.
     The notable difference is that <code>:gui</code> doesn&rsquo;t automatically create a console
     window. The default is <code>:console</code>.
</p>
</dd>
</dl>

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

<dl compact="compact">
<dt><em><code>*standard-output*</code>, <code>*debug-io*</code>, etc.</em></dt>
<dd><p>Everything related to open streams is necessarily changed, since
    the <code>os</code> won&rsquo;t let us preserve a stream across save and load.
</p>

</dd>
<dt><em><code>*default-pathname-defaults*</code></em></dt>
<dd><p>This is reinitialized to reflect the working directory where the
    saved core is loaded.
</p>
</dd>
</dl>

<p><code>save-lisp-and-die</code> interacts with <code>sb-alien:load-shared-object:</code> see its
documentation for details.
</p>
<p>On threaded platforms only a single thread may remain running after
<code>sb-ext:*save-hooks*</code> have run. Applications using multiple threads can
be <code>save-lisp-and-die</code> friendly by registering a save-hook that quits
any additional threads, and an init-hook that restarts them.
</p>
<p>This implementation is not as polished and painless as you might like:
</p><ul>
<li> 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.
</li><li> 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.
</li></ul>
<p>This isn&rsquo;t because we like it this way, but just because there don&rsquo;t
seem to be good quick fixes for either limitation and no one has been
sufficiently motivated to do lengthy fixes.
</p></dd></dl>
<a name="Variable-sb_002dext_003a_002asave_002dhooks_002a"></a><dl>
<dt><a name="index-_002asave_002dhooks_002a"></a>Variable: <strong>*save-hooks*</strong> <em>[sb-ext]</em></dt>
<dd><p>A list of function designators which are called in an unspecified
order before creating a saved core image.
</p>
<p>Unused by <code>sbcl</code> itself: reserved for user and applications.
</p></dd></dl>

<p>In cases where the standard initialization files have already been loaded
into the saved core, and alternative ones should be used (or none at all),
SBCL allows customizing the initfile pathname computation.
</p>
<a name="Variable-sb_002dext_003a_002asysinit_002dpathname_002dfunction_002a"></a><dl>
<dt><a name="index-_002asysinit_002dpathname_002dfunction_002a"></a>Variable: <strong>*sysinit-pathname-function*</strong> <em>[sb-ext]</em></dt>
<dd><p>Designator for a function of zero arguments called to obtain a
pathname designator for the default sysinit file, or <code>nil</code>. If the
function returns <code>nil</code>, no sysinit file is used unless one has been
specified on the command-line.
</p></dd></dl>
<a name="Variable-sb_002dext_003a_002auserinit_002dpathname_002dfunction_002a"></a><dl>
<dt><a name="index-_002auserinit_002dpathname_002dfunction_002a"></a>Variable: <strong>*userinit-pathname-function*</strong> <em>[sb-ext]</em></dt>
<dd><p>Designator for a function of zero arguments called to obtain a
pathname designator or a stream for the default userinit file, or <code>nil</code>.
If the function returns <code>nil</code>, no userinit file is used unless one has
been specified on the command-line.
</p></dd></dl>

<p>To facilitate distribution of SBCL applications using external
resources, the filesystem location of the SBCL core file being used is
available from Lisp.
</p>
<a name="Variable-sb_002dext_003a_002acore_002dpathname_002a"></a><dl>
<dt><a name="index-_002acore_002dpathname_002a"></a>Variable: <strong>*core-pathname*</strong> <em>[sb-ext]</em></dt>
<dd><p>The absolute pathname of the running <code>sbcl</code> core.
</p></dd></dl>

<hr>
<a name="Exit-on-Errors"></a>
<div class="header">
<p>
Previous: <a href="#Saving-a-Core-Image" accesskey="p" rel="prev">Saving a Core Image</a>, Up: <a href="#Stopping-SBCL" accesskey="u" rel="up">Stopping SBCL</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Exit-on-Errors-1"></a>
<h4 class="subsection">3.2.4 Exit on Errors</h4>

<p>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 <a href="#Debugger-Entry">Debugger Entry</a>.
</p>
<hr>
<a name="Command-Line-Options"></a>
<div class="header">
<p>
Next: <a href="#Initialization-Files" accesskey="n" rel="next">Initialization Files</a>, Previous: <a href="#Stopping-SBCL" accesskey="p" rel="prev">Stopping SBCL</a>, Up: <a href="#Starting-and-Stopping" accesskey="u" rel="up">Starting and Stopping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Command-Line-Options-1"></a>
<h3 class="section">3.3 Command Line Options</h3>


<p>Command line options can be considered an advanced topic; for ordinary
interactive use, no command line arguments should be necessary.
</p>
<p>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.
</p>
<p>The full, unambiguous syntax for invoking SBCL at the command line is:
</p>
<p><code>sbcl</code> <var>runtime-option</var>* <code>--end-runtime-options</code> <var>toplevel-option</var>* <code>--end-toplevel-options</code> <var>user-options</var>*
</p>
<p>For convenience, the <code>--end-runtime-options</code> and
<code>--end-toplevel-options</code> 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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Runtime-Options" accesskey="1">Runtime Options</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Toplevel-Options" accesskey="2">Toplevel Options</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Runtime-Options"></a>
<div class="header">
<p>
Next: <a href="#Toplevel-Options" accesskey="n" rel="next">Toplevel Options</a>, Up: <a href="#Command-Line-Options" accesskey="u" rel="up">Command Line Options</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Runtime-Options-1"></a>
<h4 class="subsection">3.3.1 Runtime Options</h4>

<dl compact="compact">
<dt><code>--core <var>corefilename</var></code></dt>
<dd><p>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.
</p>
</dd>
<dt><code>--dynamic-space-size <var>megabytes</var></code></dt>
<dd><p>Size of the dynamic space reserved on startup in megabytes. Default
value is platform dependent.
</p>
</dd>
<dt><code>--control-stack-size <var>megabytes</var></code></dt>
<dd><p>Size of control stack reserved for each thread in megabytes. Default
value is 2.
</p>
</dd>
<dt><code>--noinform</code></dt>
<dd><p>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 <code>--noprint</code> and
<code>--disable-debugger</code> options.
</p>
</dd>
<dt><code>--disable-ldb</code></dt>
<dd><a name="index-ldb-1"></a>
<a name="index-ldb_002c-disabling"></a>
<a name="index-disabling-ldb"></a>
<p>Disable the low-level debugger. Only effective if SBCL is compiled
with LDB.
</p>
</dd>
<dt><code>--lose-on-corruption</code></dt>
<dd><a name="index-ldb-2"></a>
<p>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.
</p>

</dd>
<dt><code>--script <var>filename</var></code></dt>
<dd><p>As a runtime option this is equivalent to <code>--noinform</code>
<code>--disable-ldb</code> <code>--lose-on-corruption</code>
<code>--end-runtime-options</code> <code>--script</code> <var>filename</var>. See the
description of <code>--script</code> as a toplevel option below. If there
are no other command line arguments following <code>--script</code>, the
filename argument can be omitted.
</p>

</dd>
<dt><code>--merge-core-pages</code></dt>
<dd><p>When platform support is present, provide hints to the operating system
that identical pages may be shared between processes until they are
written to.  This can be useful to reduce the memory usage on systems
with multiple SBCL processes started from similar but differently-named
core files, or from compressed cores.  Without platform support, do
nothing.
</p>

</dd>
<dt><code>--no-merge-core-pages</code></dt>
<dd><p>Ensures that no sharing hint is provided to the operating system.
</p>

</dd>
<dt><code>--default-merge-core-pages</code></dt>
<dd><p>Reverts the sharing hint policy to the default: only compressed cores
trigger hinting.  Uncompressed cores are mapped directly from the core
file, which is usually enough to ensure sharing.
</p>

</dd>
<dt><code>--help</code></dt>
<dd><p>Print some basic information about SBCL, then exit.
</p>
</dd>
<dt><code>--version</code></dt>
<dd><p>Print SBCL&rsquo;s version information, then exit.
</p>
</dd>
</dl>

<p>In the future, runtime options may be added to control behaviour such
as lazy allocation of memory.
</p>
<p>Runtime options, including any &ndash;end-runtime-options option, are
stripped out of the command line before the Lisp toplevel logic gets a
chance to see it.
</p>
<hr>
<a name="Toplevel-Options"></a>
<div class="header">
<p>
Previous: <a href="#Runtime-Options" accesskey="p" rel="prev">Runtime Options</a>, Up: <a href="#Command-Line-Options" accesskey="u" rel="up">Command Line Options</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Toplevel-Options-1"></a>
<h4 class="subsection">3.3.2 Toplevel Options</h4>

<dl compact="compact">
<dt><code>--sysinit <var>filename</var></code></dt>
<dd><p>Load filename instead of the default system initialization file
(see <a href="#Initialization-Files">Initialization Files</a>.)
</p>
</dd>
<dt><code>--no-sysinit</code></dt>
<dd><p>Don&rsquo;t load a system-wide initialization file.  If this option is given,
the <code>--sysinit</code> option is ignored.
</p>
</dd>
<dt><code>--userinit <var>filename</var></code></dt>
<dd><p>Load filename instead of the default user initialization file
(see <a href="#Initialization-Files">Initialization Files</a>.)
</p>
</dd>
<dt><code>--no-userinit</code></dt>
<dd><p>Don&rsquo;t load a user initialization file.  If this option is given,
the <code>--userinit</code> option is ignored.
</p>
</dd>
<dt><code>--eval <var>command</var></code></dt>
<dd><p>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 <code>--eval</code> option can be used, and all will be
read and executed, in the order they appear on the command line.
</p>
</dd>
<dt><code>--load <var>filename</var></code></dt>
<dd><p>This is equivalent to <code>--eval '(load &quot;<var>filename</var>&quot;)'</code>. The
special syntax is intended to reduce quoting headaches when invoking
SBCL from shell scripts.
</p>
</dd>
<dt><code>--noprint</code></dt>
<dd><p>When ordinarily the toplevel &quot;read-eval-print loop&quot; would be executed,
execute a &quot;read-eval loop&quot; instead, i.e. don&rsquo;t print a prompt and
don&rsquo;t echo results. Combined with the <code>--noinform</code> runtime
option, this makes it easier to write Lisp &quot;scripts&quot; which work
cleanly in Unix pipelines.
</p>
</dd>
<dt><code>--disable-debugger</code></dt>
<dd><p>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 <code>--eval</code> and
<code>--load</code> options. See <code>sb-ext:disable-debugger</code> for details.
See <a href="#Debugger-Entry">Debugger Entry</a>.
</p>
</dd>
<dt><code>--script <var>filename</var></code></dt>
<dd><p>Implies <code>--no-userinit</code> <code>--no-sysinit</code>
<code>--disable-debugger</code> <code>--end-toplevel-options</code>.
</p>
<p>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.
</p>
<p>If there are no other command line arguments following, the filename
can be omitted: this causes the script to be loaded from standard
input instead. Shebang lines in standard input script are currently
<em>not</em> ignored.
</p>
<p>In either case, if there is an unhandled error (e.g. end of file, or a
broken pipe) on either standard input, standard output, or standard
error, the script silently exits with code 0. This allows e.g. safely
piping output from SBCL to <code>head -n1</code> or similar.
</p>
</dd>
</dl>

<hr>
<a name="Initialization-Files"></a>
<div class="header">
<p>
Next: <a href="#Initialization-and-Exit-Hooks" accesskey="n" rel="next">Initialization and Exit Hooks</a>, Previous: <a href="#Command-Line-Options" accesskey="p" rel="prev">Command Line Options</a>, Up: <a href="#Starting-and-Stopping" accesskey="u" rel="up">Starting and Stopping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Initialization-Files-1"></a>
<h3 class="section">3.4 Initialization Files</h3>

<p>SBCL processes initialization files with <code>read</code> and <code>eval</code>,
not <code>load</code>; hence initialization files can be used to set startup
<code>*package*</code> and <code>*readtable*</code>, and for proclaiming a global
optimization policy.
</p>
<ul class="no-bullet">
<li><!-- /@w --> <strong>System Initialization File</strong>

<p>Defaults to <samp><code>$SBCL_HOME</code>/sbclrc</samp>, or if that doesn&rsquo;t exist to
<samp>/etc/sbclrc</samp>. Can be overridden with the command line option
<code>--sysinit</code> or <code>--no-sysinit</code>.
</p>
<p>The system initialization file is intended for system administrators
and software packagers to configure locations of installed third party
modules, etc.
</p>
</li><li><!-- /@w --> <strong>User Initialization File</strong>

<p>Defaults to <samp><code>$HOME</code>/.sbclrc</samp>. Can be overridden with the
command line option <code>--userinit</code> or <code>--no-userinit</code>.
</p>
<p>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 (see <a href="#FASL-Format">FASL Format</a>), etc.
</p>
</li></ul>

<p>Neither initialization file is required.
</p>
<hr>
<a name="Initialization-and-Exit-Hooks"></a>
<div class="header">
<p>
Previous: <a href="#Initialization-Files" accesskey="p" rel="prev">Initialization Files</a>, Up: <a href="#Starting-and-Stopping" accesskey="u" rel="up">Starting and Stopping</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Initialization-and-Exit-Hooks-1"></a>
<h3 class="section">3.5 Initialization and Exit Hooks</h3>

<p>SBCL provides hooks into the system initialization and exit.
</p>
<a name="Variable-sb_002dext_003a_002ainit_002dhooks_002a"></a><dl>
<dt><a name="index-_002ainit_002dhooks_002a"></a>Variable: <strong>*init-hooks*</strong> <em>[sb-ext]</em></dt>
<dd><p>A list of function designators which are called in an unspecified
order when a saved core image starts up, after the system itself has
been initialized.
</p>
<p>Unused by <code>sbcl</code> itself: reserved for user and applications.
</p></dd></dl>
<a name="Variable-sb_002dext_003a_002aexit_002dhooks_002a"></a><dl>
<dt><a name="index-_002aexit_002dhooks_002a"></a>Variable: <strong>*exit-hooks*</strong> <em>[sb-ext]</em></dt>
<dd><p>A list of function designators which are called in an unspecified
order when <code>sbcl</code> process exits.
</p>
<p>Unused by <code>sbcl</code> itself: reserved for user and applications.
</p>
<p>Using <code>(sb-ext:exit :abort t)</code>, or calling exit(3) directly circumvents
these hooks.
</p></dd></dl>

<hr>
<a name="Compiler"></a>
<div class="header">
<p>
Next: <a href="#Debugger" accesskey="n" rel="next">Debugger</a>, Previous: <a href="#Starting-and-Stopping" accesskey="p" rel="prev">Starting and Stopping</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Compiler-1"></a>
<h2 class="chapter">4 Compiler</h2>

<p>This chapter will discuss most compiler issues other than efficiency,
including compiler error messages, the SBCL compiler&rsquo;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, <a href="#Efficiency">Efficiency</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Diagnostic-Messages" accesskey="1">Diagnostic Messages</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Handling-of-Types" accesskey="2">Handling of Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Compiler-Policy" accesskey="3">Compiler Policy</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Compiler-Errors" accesskey="4">Compiler Errors</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Open-Coding-and-Inline-Expansion" accesskey="5">Open Coding and Inline Expansion</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Interpreter" accesskey="6">Interpreter</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Diagnostic-Messages"></a>
<div class="header">
<p>
Next: <a href="#Handling-of-Types" accesskey="n" rel="next">Handling of Types</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Diagnostic-Messages-1"></a>
<h3 class="section">4.1 Diagnostic Messages</h3>
<a name="index-Messages_002c-Compiler"></a>
<a name="index-Compiler-messages"></a>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Controlling-Verbosity" accesskey="1">Controlling Verbosity</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Diagnostic-Severity" accesskey="2">Diagnostic Severity</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Understanding-Compiler-Diagnostics" accesskey="3">Understanding Compiler Diagnostics</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Controlling-Verbosity"></a>
<div class="header">
<p>
Next: <a href="#Diagnostic-Severity" accesskey="n" rel="next">Diagnostic Severity</a>, Up: <a href="#Diagnostic-Messages" accesskey="u" rel="up">Diagnostic Messages</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Controlling-Verbosity-1"></a>
<h4 class="subsection">4.1.1 Controlling Verbosity</h4>

<p>The compiler can be quite verbose in its diagnostic reporting, rather
more then some users would prefer &ndash; the amount of noise emitted can
be controlled, however.
</p>
<p>To control emission of compiler diagnostics (of any severity other
than <code>error</code>: see <a href="#Diagnostic-Severity">Diagnostic Severity</a>) use the
<code>sb-ext:muffle-conditions</code> and <code>sb-ext:unmuffle-conditions</code>
declarations, specifying the type of condition that is to be muffled
(the muffling is done using an associated <code>muffle-warning</code> restart).
</p>
<p>Global control:
</p><div class="lisp">
<pre class="lisp">;;; Muffle compiler-notes globally
(declaim (sb-ext:muffle-conditions sb-ext:compiler-note))
</pre></div>

<p>Local control:
</p><div class="lisp">
<pre class="lisp">;;; 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))))
</pre></div>

<dl>
<dt><a name="index-muffle_002dconditions"></a>Declaration: <strong>muffle-conditions</strong> <em>[sb-ext]</em></dt>
<dd><p>Syntax: type*
</p>
<p>Muffles the diagnostic messages that would be caused by compile-time
signals of given types.
</p></dd></dl>

<dl>
<dt><a name="index-unmuffle_002dconditions"></a>Declaration: <strong>unmuffle-conditions</strong> <em>[sb-ext]</em></dt>
<dd><p>Syntax: type*
</p>
<p>Cancels the effect of a previous <code>sb-ext:muffle-conditions</code>
declaration.
</p></dd></dl>

<p>Various details of <em>how</em> the compiler messages are printed can be
controlled via the alist
<code>sb-ext:*compiler-print-variable-alist*</code>.
</p>
<a name="Variable-sb_002dext_003a_002acompiler_002dprint_002dvariable_002dalist_002a"></a><dl>
<dt><a name="index-_002acompiler_002dprint_002dvariable_002dalist_002a"></a>Variable: <strong>*compiler-print-variable-alist*</strong> <em>[sb-ext]</em></dt>
<dd><p>an association list describing new bindings for special variables
to be used by the compiler for error-reporting, etc. Eg.
</p>
<div class="lisp">
<pre class="lisp"> ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
</pre></div>

<p>The variables in the <code>car</code> positions are bound to the values in the <code>cdr</code>
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.
</p>
<p>Initially empty, <code>*compiler-print-variable-alist*</code> is Typically used to
specify bindings for printer control variables.
</p></dd></dl>

<p>For information about muffling warnings signaled outside of the
compiler, see <a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a>.
</p>

<hr>
<a name="Diagnostic-Severity"></a>
<div class="header">
<p>
Next: <a href="#Understanding-Compiler-Diagnostics" accesskey="n" rel="next">Understanding Compiler Diagnostics</a>, Previous: <a href="#Controlling-Verbosity" accesskey="p" rel="prev">Controlling Verbosity</a>, Up: <a href="#Diagnostic-Messages" accesskey="u" rel="up">Diagnostic Messages</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Diagnostic-Severity-1"></a>
<h4 class="subsection">4.1.2 Diagnostic Severity</h4>
<a name="index-Severity-of-compiler-messages"></a>
<a name="index-Compiler-Diagnostic-Severity"></a>
<a name="index-error-_005bcl_005d"></a>
<a name="index-warning-_005bcl_005d"></a>
<a name="index-style_002dwarning-_005bcl_005d"></a>
<a name="index-compiler_002dnote-_005bsb_002dext_005d"></a>
<a name="index-code_002ddeletion_002dnote-_005bsb_002dext_005d"></a>

<p>There are four levels of compiler diagnostic severity:
</p>
<ol>
<li> error
</li><li> warning
</li><li> style warning
</li><li> note
</li></ol>

<p>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 <code>compile</code> and <code>compile-file</code> functions.
These levels of compiler error severity occur when the compiler
handles conditions of these classes.
</p>
<p>The fourth level of compiler error severity, <em>note</em>, corresponds
to the <code>sb-ext:compiler-note</code>, and is used for problems which are
too mild for the standard condition classes, typically hints about how
efficiency might be improved. The <code>sb-ext:code-deletion-note</code>, a
subtype of <code>compiler-note</code>, is signalled when the compiler
deletes user-supplied code after proving that the code in question is
unreachable.
</p>
<p>Future work for SBCL includes expanding this hierarchy of types to
allow more fine-grained control over emission of diagnostic messages.
</p>
<a name="Condition-sb_002dext_003acompiler_002dnote"></a><dl>
<dt><a name="index-compiler_002dnote"></a>Condition: <strong>compiler-note</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>compiler-note, condition, t</code>
</p>
<p>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 <code>style-warning</code> (or any more serious condition).
</p></dd></dl>
<a name="Condition-sb_002dext_003acode_002ddeletion_002dnote"></a><dl>
<dt><a name="index-code_002ddeletion_002dnote"></a>Condition: <strong>code-deletion-note</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>code-deletion-note, compiler-note, condition, t</code>
</p>
<p>A condition type signalled when the compiler deletes code that the user
has written, having proved that it is unreachable.
</p></dd></dl>


<hr>
<a name="Understanding-Compiler-Diagnostics"></a>
<div class="header">
<p>
Previous: <a href="#Diagnostic-Severity" accesskey="p" rel="prev">Diagnostic Severity</a>, Up: <a href="#Diagnostic-Messages" accesskey="u" rel="up">Diagnostic Messages</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Understanding-Compile-Diagnostics"></a>
<h4 class="subsection">4.1.3 Understanding Compile Diagnostics</h4>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(defmacro zoq (x)
  `(roq (ploq (+ ,x 3))))

(defun foo (y)
  (declare (symbol y))
  (zoq y))
</pre></div>

<p>The main problem with this program is that it is trying to add
<code>3</code> to a symbol. Note also that the functions <code>roq</code> and
<code>ploq</code> aren&rsquo;t defined anywhere.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#The-Parts-of-a-Compiler-Diagnostic" accesskey="1">The Parts of a Compiler Diagnostic</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#The-Original-and-Actual-Source" accesskey="2">The Original and Actual Source</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#The-Processing-Path" accesskey="3">The Processing Path</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="The-Parts-of-a-Compiler-Diagnostic"></a>
<div class="header">
<p>
Next: <a href="#The-Original-and-Actual-Source" accesskey="n" rel="next">The Original and Actual Source</a>, Up: <a href="#Understanding-Compiler-Diagnostics" accesskey="u" rel="up">Understanding Compiler Diagnostics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Parts-of-a-Compiler-Diagnostic-1"></a>
<h4 class="subsubsection">4.1.3.1 The Parts of a Compiler Diagnostic</h4>

<p>When processing this program, the compiler will produce this warning:
</p>
<div class="example">
<pre class="example">; file: /tmp/foo.lisp
; in: DEFUN FOO
;     (ZOQ Y)
; --&gt; ROQ PLOQ
; ==&gt;
;   (+ Y 3)
;
; caught WARNING:
;   Asserted type NUMBER conflicts with derived type (VALUES SYMBOL &amp;OPTIONAL).
</pre></div>

<p>In this example we see each of the six possible parts of a compiler
diagnostic:
</p>
<ol>
<li> <a name="index-with_002dcompilation_002dunit-_005bcl_005d"></a>
&lsquo;<samp>file: /tmp/foo.lisp</samp>&rsquo; 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
<code>with-compilation-unit</code> is used to delay undefined warnings.

</li><li> &lsquo;<samp>in: DEFUN FOO</samp>&rsquo; 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
&ldquo;&lsquo;<samp>def</samp>&rsquo;&rdquo;. If there is no such enclosing &ldquo;&lsquo;<samp>def</samp>&rsquo;&rdquo; form,
then the outermost form is used. If there are multiple &lsquo;<samp>def</samp>&rsquo;
forms, then they are all printed from the outside in, separated by
&lsquo;<samp>=&gt;</samp>&rsquo;&rsquo;s. In this example, the problem was in the <code>defun</code> for
<code>foo</code>.

</li><li> <a name="index-Original-Source"></a>
&lsquo;<samp>(ZOQ Y)</samp>&rsquo; This is the <em>original source</em> 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
<code>compile</code> or in the top level form read from the source file. In
this example, the expansion of the <code>zoq</code> macro was responsible
for the message.

</li><li> <a name="index-Processing-Path"></a>
&lsquo;<samp>--&gt; ROQ PLOQ</samp>&rsquo; This is the <em>processing path</em> 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 <code>roq</code> and <code>ploq</code>. These calls resulted from the
expansion of the <code>zoq</code> macro.

</li><li> <a name="index-Actual-Source"></a>
&lsquo;<samp>==&gt; (+ Y 3)</samp>&rsquo; This is the <em>actual source</em> 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 <code>y</code>.

</li><li> &lsquo;<samp>caught WARNING: Asserted type NUMBER conflicts with derived type
(VALUES SYMBOL &amp;OPTIONAL).</samp>&rsquo;  This is the <em>explanation</em> of the
problem. In this example, the problem is that, while the call to
<code>+</code> requires that its arguments are all of type <code>number</code>,
the compiler has derived that <code>y</code> will evaluate to a
<code>symbol</code>.  Note that &lsquo;<samp>(VALUES SYMBOL &amp;OPTIONAL)</samp>&rsquo; expresses
that <code>y</code> evaluates to precisely one value.

</li></ol>

<p>Note that each part of the message is distinctively marked:
</p>
<ul>
<li> &lsquo;<samp>file:</samp>&rsquo; and &lsquo;<samp>in:</samp>&rsquo; mark the file and definition,
respectively.

</li><li> The original source is an indented form with no prefix.

</li><li> Each line of the processing path is prefixed with &lsquo;<samp>--&gt;</samp>&rsquo;

</li><li> The actual source form is indented like the original source, but is
marked by a preceding &lsquo;<samp>==&gt;</samp>&rsquo; line.

</li><li> The explanation is prefixed with the diagnostic severity, which can be
&lsquo;<samp>caught ERROR:</samp>&rsquo;, &lsquo;<samp>caught WARNING:</samp>&rsquo;, &lsquo;<samp>caught
STYLE-WARNING:</samp>&rsquo;, or &lsquo;<samp>note:</samp>&rsquo;.

</li></ul>

<p>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:
</p>
<div class="example">
<pre class="example">; file: /tmp/foo.lisp
; in: DEFUN FOO
;     (ZOQ Y)
; --&gt; ROQ
; ==&gt;
;   (PLOQ (+ Y 3))
;
; caught STYLE-WARNING:
;   undefined function: PLOQ

; ==&gt;
;   (ROQ (PLOQ (+ Y 3)))
;
; caught STYLE-WARNING:
;   undefined function: ROQ
</pre></div>

<p>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: &lsquo;<samp>[Last
message occurs <var>repeats</var> times]</samp>&rsquo; where <var>repeats</var> is the number
of times the message was given.
</p>
<p>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.
</p>

<hr>
<a name="The-Original-and-Actual-Source"></a>
<div class="header">
<p>
Next: <a href="#The-Processing-Path" accesskey="n" rel="next">The Processing Path</a>, Previous: <a href="#The-Parts-of-a-Compiler-Diagnostic" accesskey="p" rel="prev">The Parts of a Compiler Diagnostic</a>, Up: <a href="#Understanding-Compiler-Diagnostics" accesskey="u" rel="up">Understanding Compiler Diagnostics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Original-and-Actual-Source-1"></a>
<h4 class="subsubsection">4.1.3.2 The Original and Actual Source</h4>
<a name="index-Original-Source-1"></a>
<a name="index-Actual-Source-1"></a>

<p>The <em>original source</em> 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.)
</p>
<p>When the <em>actual source</em> 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.
</p>
<p>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
</p>
<div class="lisp">
<pre class="lisp">(defun bar (x)
  (let (a)
    (declare (fixnum a))
    (setq a (foo x))
    a))
</pre></div>

<p>gives this error message
</p>
<div class="example">
<pre class="example">; 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 &amp;OPTIONAL).
</pre></div>

<p>This message is not saying &ldquo;there is a problem somewhere in this
<code>let</code>&rdquo; &ndash; it is saying that there is a problem with the
<code>let</code> itself. In this example, the problem is that <code>a</code>&rsquo;s
<code>nil</code> initial value is not a <code>fixnum</code>.
</p>
<hr>
<a name="The-Processing-Path"></a>
<div class="header">
<p>
Previous: <a href="#The-Original-and-Actual-Source" accesskey="p" rel="prev">The Original and Actual Source</a>, Up: <a href="#Understanding-Compiler-Diagnostics" accesskey="u" rel="up">Understanding Compiler Diagnostics</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Processing-Path-1"></a>
<h4 class="subsubsection">4.1.3.3 The Processing Path</h4>
<a name="index-Processing-Path-1"></a>
<a name="index-Macroexpansion"></a>
<a name="index-Source_002dto_002dsource-transformation"></a>

<p>The processing path is mainly useful for debugging macros, so if you
don&rsquo;t write macros, you can probably ignore it. Consider this example:
</p>
<div class="lisp">
<pre class="lisp">(defun foo (n)
  (dotimes (i n *undefined*)))
</pre></div>

<p>Compiling results in this error message:
</p>
<div class="example">
<pre class="example">; in: DEFUN FOO
;     (DOTIMES (I N *UNDEFINED*))
; --&gt; DO BLOCK LET TAGBODY RETURN-FROM
; ==&gt;
;   (PROGN *UNDEFINED*)
;
; caught WARNING:
;   undefined variable: *UNDEFINED*
</pre></div>

<p>Note that <code>do</code> appears in the processing path. This is because
<code>dotimes</code> expands into:
</p>
<div class="lisp">
<pre class="lisp">(do ((i 0 (1+ i)) (#:g1 n))
    ((&gt;= i #:g1) *undefined*)
  (declare (type unsigned-byte i)))
</pre></div>

<p>The rest of the processing path results from the expansion of
<code>do</code>:
</p>
<div class="lisp">
<pre class="lisp">(block nil
  (let ((i 0) (#:g1 n))
    (declare (type unsigned-byte i))
    (tagbody (go #:g3)
      #:g2    (psetq i (1+ i))
      #:g3    (unless (&gt;= i #:g1) (go #:g2))
      (return-from nil (progn *undefined*)))))
</pre></div>

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




<hr>
<a name="Handling-of-Types"></a>
<div class="header">
<p>
Next: <a href="#Compiler-Policy" accesskey="n" rel="next">Compiler Policy</a>, Previous: <a href="#Diagnostic-Messages" accesskey="p" rel="prev">Diagnostic Messages</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Handling-of-Types-1"></a>
<h3 class="section">4.2 Handling of Types</h3>

<p>One of the most important features of the SBCL compiler (similar to
the original CMUCL compiler, also known as <em>Python</em>) is its fairly
sophisticated understanding of the Common Lisp type system and its
conservative approach to the implementation of type declarations.
</p>
<p>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 (see <a href="#Efficiency">Efficiency</a>), the use
of appropriate type declarations can be very important for performance
as well.
</p>
<a name="index-satisfies-_005bcl_005d"></a>
<p>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 <code>satisfies</code> type specifier.
</p>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Declarations-as-Assertions" accesskey="1">Declarations as Assertions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Precise-Type-Checking" accesskey="2">Precise Type Checking</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Getting-Existing-Programs-to-Run" accesskey="3">Getting Existing Programs to Run</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Implementation-Limitations" accesskey="4">Implementation Limitations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Declarations-as-Assertions"></a>
<div class="header">
<p>
Next: <a href="#Precise-Type-Checking" accesskey="n" rel="next">Precise Type Checking</a>, Up: <a href="#Handling-of-Types" accesskey="u" rel="up">Handling of Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Declarations-as-Assertions-1"></a>
<h4 class="subsection">4.2.1 Declarations as Assertions</h4>
<a name="index-Safety-optimization-quality"></a>

<p>The SBCL compiler treats type declarations differently from most other
Lisp compilers. Under default compilation policy the compiler doesn&rsquo;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.
</p>
<blockquote>
<p><em>Remaining bugs in the compiler&rsquo;s handling of types unfortunately
provide some exceptions to this rule, see <a href="#Implementation-Limitations">Implementation Limitations</a>.</em>
</p></blockquote>

<p>CLOS slot types form a notable exception. Types declared using the
<code>:type</code> slot option in <code>defclass</code> are asserted if and only
if the class was defined in <em>safe code</em> and the slot access
location is in <em>safe code</em> 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.
</p>
<p>There are three type checking policies available in SBCL, selectable
via <code>optimize</code> declarations.
</p>
<dl compact="compact">
<dt><strong>Full Type Checks</strong></dt>
<dd><p>All declarations are considered assertions to be checked at runtime,
and all type checks are precise. The default compilation policy
provides full type checks.
</p>
<p>Used when <code>(or (&gt;= safety 2) (&gt;= safety speed 1))</code>.
</p>
</dd>
<dt><strong>Weak Type Checks</strong></dt>
<dd><p>Declared types may be simplified into faster to check supertypes: for
example, <code>(or (integer -17 -7) (integer 7 17))</code> is simplified
into <code>(integer -17 17)</code>.
</p>
<p><strong>Note</strong>: it is relatively easy to corrupt the heap when weak
type checks are used if the program contains type-errors.
</p>
<p>Used when <code>(and (&lt; safety 2) (&lt; safety speed))</code>
</p>
</dd>
<dt><strong>No Type Checks</strong></dt>
<dd><p>All declarations are believed without assertions. Also disables
argument count and array bounds checking.
</p>
<p><strong>Note</strong>: any type errors in code where type checks are not
performed are liable to corrupt the heap.
</p>
<p>Used when <code>(= safety 0)</code>.
</p>
</dd>
</dl>

<hr>
<a name="Precise-Type-Checking"></a>
<div class="header">
<p>
Next: <a href="#Getting-Existing-Programs-to-Run" accesskey="n" rel="next">Getting Existing Programs to Run</a>, Previous: <a href="#Declarations-as-Assertions" accesskey="p" rel="prev">Declarations as Assertions</a>, Up: <a href="#Handling-of-Types" accesskey="u" rel="up">Handling of Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Precise-Type-Checking-1"></a>
<h4 class="subsection">4.2.2 Precise Type Checking</h4>
<a name="index-Precise-type-checking"></a>
<a name="index-Type-checking_002c-precise"></a>

<p>Precise checking means that the check is done as though <code>typep</code>
had been called with the exact type specifier that appeared in the
declaration.
</p>
<p>If a variable is declared to be <code>(integer 3 17)</code> then its value
must always be an integer between <code>3</code> and <code>17</code>. 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 <code>and</code> type specifier.
</p>
<p>To gain maximum benefit from the compiler&rsquo;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 <code>or</code>,
<code>member</code>, and other list-style type specifiers.
</p>

<hr>
<a name="Getting-Existing-Programs-to-Run"></a>
<div class="header">
<p>
Next: <a href="#Implementation-Limitations" accesskey="n" rel="next">Implementation Limitations</a>, Previous: <a href="#Precise-Type-Checking" accesskey="p" rel="prev">Precise Type Checking</a>, Up: <a href="#Handling-of-Types" accesskey="u" rel="up">Handling of Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Getting-Existing-Programs-to-Run-1"></a>
<h4 class="subsection">4.2.3 Getting Existing Programs to Run</h4>
<a name="index-Existing-programs_002c-to-run"></a>
<a name="index-Types_002c-portability"></a>
<a name="index-Compatibility-with-other-Lisps"></a>

<p>Since SBCL&rsquo;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.
</p>
<p>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 <code>safety</code> optimization) and then test this
safe version. After the checking version has been tested, then you can
consider weakening or eliminating type checks.  <em>This applies
even to previously debugged programs,</em> because the SBCL compiler does
much more type inference than other Common Lisp compilers, so an
incorrect declaration can do more damage.
</p>
<p>The most common problem is with variables whose constant initial value
doesn&rsquo;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:
</p>
<div class="lisp">
<pre class="lisp">(prog (foo)
  (declare (fixnum foo))
  (setq foo ...)
  ...)
</pre></div>

<p>Here <code>foo</code> is given an initial value of <code>nil</code>, but is
declared to be a <code>fixnum</code>.  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
</p>
<div class="lisp">
<pre class="lisp">(prog (foo)
  (declare (type (or fixnum null) foo))
  (setq foo ...)
  ...)
</pre></div>

<p>or change the initial value
</p>
<div class="lisp">
<pre class="lisp">(prog ((foo 0))
  (declare (fixnum foo))
  (setq foo ...)
  ...)
</pre></div>

<p>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.
</p>
<p>Another declaration problem occasionally encountered is incorrect
declarations on <code>defmacro</code> arguments. This can happen when a
function is converted into a macro. Consider this macro:
</p>
<div class="lisp">
<pre class="lisp">(defmacro my-1+ (x)
  (declare (fixnum x))
  `(the fixnum (1+ ,x)))
</pre></div>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(my-1+ (+ 4 5))
</pre></div>

<p>This call is illegal because the argument to the macro is <code>(+ 4
5)</code>, which is a <code>list</code>, not a <code>fixnum</code>.  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 <code>the</code> in
the expansion:
</p>
<div class="lisp">
<pre class="lisp">(defmacro my-1+ (x)
  `(the fixnum (1+ (the fixnum ,x))))
</pre></div>

<p>In this case, it would be stylistically preferable to change this
macro back to a function and declare it inline.
</p>
<p>Some more subtle problems are caused by incorrect declarations that
can&rsquo;t be detected at compile time.  Consider this code:
</p>
<div class="lisp">
<pre class="lisp">(do ((pos 0 (position #\a string :start (1+ pos))))
  ((null pos))
  (declare (fixnum pos))
  ...)
</pre></div>

<p>Although <code>pos</code> is almost always a <code>fixnum</code>, it is <code>nil</code>
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 <code>position</code> will complain
because <code>(1+ nil)</code> isn&rsquo;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 <code>pos</code> is
always a <code>fixnum</code>, it believes that <code>pos</code> is never
<code>nil</code>, so <code>(null pos)</code> 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.
</p>
<p>In this case, the fix is to weaken the type declaration to <code>(or
fixnum null)</code> <a name="DOCF2" href="#FOOT2"><sup>2</sup></a>.
</p>
<p>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 <code>fixnum</code>, since <code>nil</code> is not a
legal numeric argument. Another possible fix would be to say:
</p>
<div class="lisp">
<pre class="lisp">(do ((pos 0 (position #\a string :start (1+ pos))))
    ((null pos))
  (let ((pos pos))
    (declare (fixnum pos))
    ...))
</pre></div>

<p>This would be preferable in some circumstances, since it would allow a
non-standard representation to be used for the local <code>pos</code>
variable in the loop body.
</p>
<hr>
<a name="Implementation-Limitations"></a>
<div class="header">
<p>
Previous: <a href="#Getting-Existing-Programs-to-Run" accesskey="p" rel="prev">Getting Existing Programs to Run</a>, Up: <a href="#Handling-of-Types" accesskey="u" rel="up">Handling of Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Implementation-Limitations-1"></a>
<h4 class="subsection">4.2.4 Implementation Limitations</h4>

<p>Ideally, the compiler would consider <em>all</em> type declarations to
be assertions, so that adding type declarations to a program, no
matter how incorrect they might be, would <em>never</em> cause undefined
behavior. However, the compiler is known to fall short of this goal in
two areas:
</p>
<ul>
<li> <em>Proclaimed</em> 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.

</li><li> 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.

<p>For example,
</p>
<div class="lisp">
<pre class="lisp">(defun foo (x)
  (the integer (bar x)))
</pre></div>

<p>causes the following compiler diagnostic to be emitted:
</p>
<div class="example">
<pre class="example">; note: type assertion too complex to check:
;  (VALUES INTEGER &amp;REST T).
</pre></div>

<p>A partial workaround is instead write:
</p>
<div class="lisp">
<pre class="lisp">(defun foo (x)
  (the (values integer &amp;optional) (bar x)))
</pre></div>

</li></ul>

<p>These are important issues, but are not necessarily easy to fix, so
they may, alas, remain in the system for a while.
</p>
<hr>
<a name="Compiler-Policy"></a>
<div class="header">
<p>
Next: <a href="#Compiler-Errors" accesskey="n" rel="next">Compiler Errors</a>, Previous: <a href="#Handling-of-Types" accesskey="p" rel="prev">Handling of Types</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Compiler-Policy-1"></a>
<h3 class="section">4.3 Compiler Policy</h3>

<p>Compiler policy is controlled by the <code>optimize</code> declaration,
supporting all ANSI optimization qualities (<code>debug</code>,
<code>safety</code>, <code>space</code>, and <code>speed</code>).<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>
</p>
<p>For effects of various optimization qualities on type-safety and
debuggability see <a href="#Declarations-as-Assertions">Declarations as Assertions</a> and <a href="#Debugger-Policy-Control">Debugger Policy Control</a>.
</p>
<p>Ordinarily, when the <code>speed</code> quality is high, the compiler emits
notes to notify the programmer about its inability to apply various
optimizations. For selective muffling of these notes See <a href="#Controlling-Verbosity">Controlling Verbosity</a>.
</p>
<p>The value of <code>space</code> mostly influences the compiler&rsquo;s decision
whether to inline operations, which tend to increase the size of
programs. Use the value <code>0</code> 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.
</p>

<a name="Function-sb_002dext_003adescribe_002dcompiler_002dpolicy"></a><dl>
<dt><a name="index-describe_002dcompiler_002dpolicy"></a>Function: <strong>describe-compiler-policy</strong> <em>[sb-ext] &amp;optional spec</em></dt>
<dd><p>Print all global optimization settings, augmented by <code>spec</code>.
</p></dd></dl>
<a name="Function-sb_002dext_003arestrict_002dcompiler_002dpolicy"></a><dl>
<dt><a name="index-restrict_002dcompiler_002dpolicy"></a>Function: <strong>restrict-compiler-policy</strong> <em>[sb-ext] &amp;optional quality min</em></dt>
<dd><p>Assign a minimum value to an optimization quality. <code>quality</code> is the name of
the optimization quality to restrict, and <code>min</code> (defaulting to zero) is the
minimum allowed value.
</p>
<p>Returns the alist describing the current policy restrictions.
</p>
<p>If <code>quality</code> is <code>nil</code> or not given, nothing is done.
</p>
<p>Otherwise, if <code>min</code> is zero or not given, any existing restrictions of <code>quality</code>
are removed. If <code>min</code> is between one and three inclusive, it becomes the new
minimum value for the optimization quality: any future proclamations or
declarations of the quality with a value less then <code>min</code> behave as if the value
was <code>min</code> instead.
</p>
<p>This is intended to be used interactively, to facilitate recompiling large
bodies of code with eg. a known minimum safety.
</p>
<p>See also <code>:policy</code> option in <code>with-compilation-unit</code>.
</p>
<p><code>experimental</code> <code>interface:</code> Subject to change.
</p></dd></dl>
<a name="Macro-common_002dlisp_003awith_002dcompilation_002dunit"></a><dl>
<dt><a name="index-with_002dcompilation_002dunit"></a>Macro: <strong>with-compilation-unit</strong> <em>[cl] options &amp;body body</em></dt>
<dd><p>Affects compilations that take place within its dynamic extent. It is
intended to be eg. wrapped around the compilation of all files in the same system.
</p>
<p>Following options are defined:
</p>

<dl compact="compact">
<dt><em><code>:override</code> Boolean-Form</em></dt>
<dd><p>One of the effects of this form is to delay undefined warnings until the
      end of the form, instead of giving them at the end of each compilation.
      If <code>override</code> is <code>nil</code> (the default), then the outermost
      <code>with-compilation-unit</code> form grabs the undefined warnings. Specifying
      <code>override</code> true causes that form to grab any enclosed warnings, even if it
      is enclosed by another <code>with-compilation-unit</code>.
</p>

</dd>
<dt><em><code>:policy</code> Optimize-Declaration-Form</em></dt>
<dd><p>Provides dynamic scoping for global compiler optimization qualities and
      restrictions, limiting effects of subsequent <code>optimize</code> proclamations and
      calls to <code>sb-ext:restrict-compiler-policy</code> to the dynamic scope of <code>body</code>.
</p>
<p>If <code>override</code> is false, specified <code>policy</code> is merged with current global
      policy. If <code>override</code> is true, current global policy, including any
      restrictions, is discarded in favor of the specified <code>policy</code>.
</p>
<p>Supplying <code>policy</code> <code>nil</code> is equivalent to the option not being supplied at
      all, ie. dynamic scoping of policy does not take place.
</p>
<p>This option is an SBCL-specific experimental extension: Interface
      subject to change.
</p>

</dd>
<dt><em><code>:source-namestring</code> Namestring-Form</em></dt>
<dd><p>Attaches the value returned by the Namestring-Form to the internal
      debug-source information as the namestring of the source file. Normally
      the namestring of the input-file for <code>compile-file</code> is used: this option
      can be used to provide source-file information for functions compiled
      using <code>compile</code>, or to override the input-file of <code>compile-file</code>.
</p>
<p>If both an outer and an inner <code>with-compilation-unit</code> provide a
      <code>source-namestring</code>, the inner one takes precedence. Unaffected
      by <code>:override</code>.
</p>
<p>This is an SBCL-specific extension.
</p>

</dd>
<dt><em><code>:source-plist</code> Plist-Form</em></dt>
<dd><p>Attaches the value returned by the Plist-Form to internal debug-source
      information of functions compiled in within the dynamic extent of <code>body</code>.
</p>
<p>Primarily for use by development environments, in order to eg. associate
      function definitions with editor-buffers. Can be accessed using
      <code>sb-introspect:definition-source-plist</code>.
</p>
<p>If an outer <code>with-compilation-unit</code> form also provide a <code>source-plist</code>, it
      is appended to the end of the provided <code>source-plist</code>. Unaffected
      by <code>:override</code>.
</p>
<p>This is an SBCL-specific extension.
</p>
</dd>
</dl>

<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">  ;; Prevent proclamations from the file leaking, and restrict
  ;; SAFETY to 3 -- otherwise uses the current global policy.
  (with-compilation-unit (:policy '(optimize))
    (restrict-compiler-policy 'safety 3)
    (load &quot;foo.lisp&quot;))

  ;; Using default policy instead of the current global one,
  ;; except for DEBUG 3.
  (with-compilation-unit (:policy '(optimize debug)
                          :override t)
    (load &quot;foo.lisp&quot;))

  ;; Same as if :POLICY had not been specified at all: SAFETY 3
  ;; proclamation leaks out from WITH-COMPILATION-UNIT.
  (with-compilation-unit (:policy nil)
    (declaim (optimize safety))
    (load &quot;foo.lisp&quot;))
</pre></div>
</dd></dl>

<hr>
<a name="Compiler-Errors"></a>
<div class="header">
<p>
Next: <a href="#Open-Coding-and-Inline-Expansion" accesskey="n" rel="next">Open Coding and Inline Expansion</a>, Previous: <a href="#Compiler-Policy" accesskey="p" rel="prev">Compiler Policy</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Compiler-Errors-1"></a>
<h3 class="section">4.4 Compiler Errors</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Type-Errors-at-Compile-Time" accesskey="1">Type Errors at Compile Time</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Errors-During-Macroexpansion" accesskey="2">Errors During Macroexpansion</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Read-Errors" accesskey="3">Read Errors</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Type-Errors-at-Compile-Time"></a>
<div class="header">
<p>
Next: <a href="#Errors-During-Macroexpansion" accesskey="n" rel="next">Errors During Macroexpansion</a>, Up: <a href="#Compiler-Errors" accesskey="u" rel="up">Compiler Errors</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Type-Errors-at-Compile-Time-1"></a>
<h4 class="subsection">4.4.1 Type Errors at Compile Time</h4>
<a name="index-Compile-time-type-errors"></a>
<a name="index-Type-checking_002c-at-compile-time"></a>

<p>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.
</p>
<p>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&rsquo;t always indicate an
incorrect program.
</p>
<p>For example, consider this code fragment:
</p>
<div class="lisp">
<pre class="lisp">(defun raz (foo)
  (let ((x (case foo
              (:this 13)
              (:that 9)
              (:the-other 42))))
    (declare (fixnum x))
    (foo x)))
</pre></div>

<p>Compilation produces this warning:
</p>
<div class="example">
<pre class="example">; in: DEFUN RAZ
;     (CASE FOO (:THIS 13) (:THAT 9) (:THE-OTHER 42))
; --&gt; LET COND IF COND IF COND IF
; ==&gt;
;   (COND)
;
; caught WARNING:
;   This is not a FIXNUM:
;   NIL
</pre></div>

<p>In this case, the warning means that if <code>foo</code> isn&rsquo;t any of
<code>:this</code>, <code>:that</code> or <code>:the-other</code>, then <code>x</code> will be
initialized to <code>nil</code>, which the <code>fixnum</code> declaration makes
illegal. The warning will go away if <code>ecase</code> is used instead of
<code>case</code>, or if <code>:the-other</code> is changed to <code>t</code>.
</p>
<p>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&rsquo;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.
</p>
<hr>
<a name="Errors-During-Macroexpansion"></a>
<div class="header">
<p>
Next: <a href="#Read-Errors" accesskey="n" rel="next">Read Errors</a>, Previous: <a href="#Type-Errors-at-Compile-Time" accesskey="p" rel="prev">Type Errors at Compile Time</a>, Up: <a href="#Compiler-Errors" accesskey="u" rel="up">Compiler Errors</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Errors-During-Macroexpansion-1"></a>
<h4 class="subsection">4.4.2 Errors During Macroexpansion</h4>
<a name="index-Macroexpansion_002c-errors-during"></a>

<p>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 <code>*break-on-signals*</code> to <code>error</code>. For
example, this definition:
</p>
<div class="lisp">
<pre class="lisp">(defun foo (e l)
  (do ((current l (cdr current))
       ((atom current) nil))
      (when (eq (car current) e) (return current))))
</pre></div>

<p>gives this error:
</p>
<div class="example">
<pre class="example">; 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)
</pre></div>


<hr>
<a name="Read-Errors"></a>
<div class="header">
<p>
Previous: <a href="#Errors-During-Macroexpansion" accesskey="p" rel="prev">Errors During Macroexpansion</a>, Up: <a href="#Compiler-Errors" accesskey="u" rel="up">Compiler Errors</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Read-Errors-1"></a>
<h4 class="subsection">4.4.3 Read Errors</h4>
<a name="index-Read-errors_002c-compiler"></a>

<p>SBCL&rsquo;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.
</p>
<hr>
<a name="Open-Coding-and-Inline-Expansion"></a>
<div class="header">
<p>
Next: <a href="#Interpreter" accesskey="n" rel="next">Interpreter</a>, Previous: <a href="#Compiler-Errors" accesskey="p" rel="prev">Compiler Errors</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Open-Coding-and-Inline-Expansion-1"></a>
<h3 class="section">4.5 Open Coding and Inline Expansion</h3>
<a name="index-Open_002dcoding"></a>
<a name="index-Inline-expansion"></a>
<a name="index-Static-functions"></a>

<p>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:
</p>
<ul>
<li> 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
<code>trace</code> macro.  Special-casing of standard functions can be
inhibited using the <code>notinline</code> declaration, but even then some
phases of analysis such as type inferencing are applied by the
compiler.

</li><li> 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, <a href="#Compiler-Policy">Compiler Policy</a>.

</li></ul>

<p>When a function call is <em>open coded</em>, inline code whose effect is
equivalent to the function call is substituted for that function
call. When a function call is <em>closed coded</em>, 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 <code>nthcdr</code> were to be
open coded, then
</p>
<div class="lisp">
<pre class="lisp">(nthcdr 4 foobar)
</pre></div>

<p>might turn into
</p>
<div class="lisp">
<pre class="lisp">(cdr (cdr (cdr (cdr foobar))))
</pre></div>

<p>or even
</p>
<div class="lisp">
<pre class="lisp">(do ((i 0 (1+ i))
  (list foobar (cdr foobar)))
  ((= i 4) list))
</pre></div>

<p>If <code>nth</code> is closed coded, then
</p>
<div class="lisp">
<pre class="lisp">(nth x l)
</pre></div>

<p>might stay the same, or turn into something like
</p>
<div class="lisp">
<pre class="lisp">(car (nthcdr x l))
</pre></div>

<p>In general, open coding sacrifices space for speed, but some functions
(such as <code>car</code>) 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 <em>static call</em>. Static function call uses
a more efficient calling convention that forbids redefinition.
</p>
<hr>
<a name="Interpreter"></a>
<div class="header">
<p>
Previous: <a href="#Open-Coding-and-Inline-Expansion" accesskey="p" rel="prev">Open Coding and Inline Expansion</a>, Up: <a href="#Compiler" accesskey="u" rel="up">Compiler</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Interpreter-1"></a>
<h3 class="section">4.6 Interpreter</h3>
<a name="index-Interpreter"></a>
<a name="index-eval-_005bcl_005d"></a>
<a name="index-_002aevaluator_002dmode_002a-_005bsb_002dext_005d"></a>

<p>By default SBCL implements <code>eval</code> by calling the native code
compiler.
</p>
<p>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.
</p>
<a name="Variable-sb_002dext_003a_002aevaluator_002dmode_002a"></a><dl>
<dt><a name="index-_002aevaluator_002dmode_002a"></a>Variable: <strong>*evaluator-mode*</strong> <em>[sb-ext]</em></dt>
<dd><p>Toggle between different evaluator implementations. If set to <code>:compile</code>,
an implementation of <code>eval</code> that calls the compiler will be used. If set
to <code>:interpret</code>, an interpreter will be used.
</p></dd></dl>
<hr>
<a name="Debugger"></a>
<div class="header">
<p>
Next: <a href="#Efficiency" accesskey="n" rel="next">Efficiency</a>, Previous: <a href="#Compiler" accesskey="p" rel="prev">Compiler</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-1"></a>
<h2 class="chapter">5 Debugger</h2>
<a name="index-Debugger"></a>

<p>This chapter documents the debugging facilities of SBCL, including
the debugger, single-stepper and <code>trace</code>, and the effect of
<code>(optimize debug)</code> declarations.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Debugger-Entry" accesskey="1">Debugger Entry</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Debugger-Command-Loop" accesskey="2">Debugger Command Loop</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Stack-Frames" accesskey="3">Stack Frames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Variable-Access" accesskey="4">Variable Access</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Source-Location-Printing" accesskey="5">Source Location Printing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Debugger-Policy-Control" accesskey="6">Debugger Policy Control</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Exiting-Commands" accesskey="7">Exiting Commands</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Information-Commands" accesskey="8">Information Commands</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Function-Tracing" accesskey="9">Function Tracing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Single-Stepping">Single Stepping</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Debugger-Entry"></a>
<div class="header">
<p>
Next: <a href="#Debugger-Command-Loop" accesskey="n" rel="next">Debugger Command Loop</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-Entry-1"></a>
<h3 class="section">5.1 Debugger Entry</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Debugger-Banner" accesskey="1">Debugger Banner</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Debugger-Invocation" accesskey="2">Debugger Invocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Debugger-Banner"></a>
<div class="header">
<p>
Next: <a href="#Debugger-Invocation" accesskey="n" rel="next">Debugger Invocation</a>, Up: <a href="#Debugger-Entry" accesskey="u" rel="up">Debugger Entry</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-Banner-1"></a>
<h4 class="subsection">5.1.1 Debugger Banner</h4>

<p>When you enter the debugger, it looks something like this:
</p>
<div class="example">
<pre class="example">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]
</pre></div>

<p>The first group of lines describe what the error was that put us in
the debugger.  In this case <code>car</code> was called on <code>3</code>, causing
a <code>type-error</code>.
</p>
<p>This is followed by the &ldquo;beginner help line&rdquo;, which appears only if
<code>sb-debug:*debug-beginner-help-p*</code> is true (default).
</p>
<p>Next comes a listing of the active restart names, along with their
descriptions &ndash; 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.
</p>
<p>The current frame appears right underneath the restarts, immediately
followed by the debugger prompt.
</p>
<hr>
<a name="Debugger-Invocation"></a>
<div class="header">
<p>
Previous: <a href="#Debugger-Banner" accesskey="p" rel="prev">Debugger Banner</a>, Up: <a href="#Debugger-Entry" accesskey="u" rel="up">Debugger Entry</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-Invocation-1"></a>
<h4 class="subsection">5.1.2 Debugger Invocation</h4>

<p>The debugger is invoked when:
</p>
<ul>
<li> <code>error</code> is called, and the condition it signals is not handled.

</li><li> <code>break</code> is called, or <code>signal</code> is called with a condition
that matches the current <code>*break-on-signals*</code>.

</li><li> the debugger is explicitly entered with the <code>invoke-debugger</code>
function.

</li></ul>

<p>When the debugger is invoked by a condition, ANSI mandates that the
value of <code>*debugger-hook*</code>, if any, be called with two arguments:
the condition that caused the debugger to be invoked and the previous
value of <code>*debugger-hook*</code>. When this happens,
<code>*debugger-hook*</code> is bound to NIL to prevent recursive errors.
However, ANSI also mandates that <code>*debugger-hook*</code> not be invoked
when the debugger is to be entered by the <code>break</code> function. For
users who wish to provide an alternate debugger interface (and thus
catch <code>break</code> entries into the debugger), SBCL provides
<code>sb-ext:*invoke-debugger-hook*</code>, which is invoked during any
entry into the debugger.
</p>
<a name="Variable-sb_002dext_003a_002ainvoke_002ddebugger_002dhook_002a"></a><dl>
<dt><a name="index-_002ainvoke_002ddebugger_002dhook_002a"></a>Variable: <strong>*invoke-debugger-hook*</strong> <em>[sb-ext]</em></dt>
<dd><p>This is either <code>nil</code> 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 <code>*invoke-debugger-hook*</code> bound to <code>nil</code> to minimize recursive
   errors, and receives as arguments the condition that triggered
   debugger entry and the previous value of <code>*invoke-debugger-hook*</code>
</p>
<p>This mechanism is an <code>sbcl</code> extension similar to the standard <code>*debugger-hook*</code>.
   In contrast to <code>*debugger-hook*</code>, it is observed by <code>invoke-debugger</code> even when
   called by <code>break</code>.
</p></dd></dl>

<hr>
<a name="Debugger-Command-Loop"></a>
<div class="header">
<p>
Next: <a href="#Stack-Frames" accesskey="n" rel="next">Stack Frames</a>, Previous: <a href="#Debugger-Entry" accesskey="p" rel="prev">Debugger Entry</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-Command-Loop-1"></a>
<h3 class="section">5.2 Debugger Command Loop</h3>

<p>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: <code>help</code>
can be typed as &lsquo;<samp>h</samp>&rsquo;, &lsquo;<samp>he</samp>&rsquo;, etc.
</p>
<p>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 <code>progn</code> to hide it from
the command loop.
</p>
<p>The debugger prompt is &ldquo;<code><var>frame</var>]</code>&rdquo;, where <var>frame</var> 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.
</p>
<p>It is possible to override the normal printing behaviour in the
debugger by using the <code>sb-ext:*debug-print-variable-alist*</code>.
</p>
<a name="Variable-sb_002dext_003a_002adebug_002dprint_002dvariable_002dalist_002a"></a><dl>
<dt><a name="index-_002adebug_002dprint_002dvariable_002dalist_002a"></a>Variable: <strong>*debug-print-variable-alist*</strong> <em>[sb-ext]</em></dt>
<dd><p>an association list describing new bindings for special variables
to be used within the debugger. Eg.
</p>
<div class="lisp">
<pre class="lisp"> ((*PRINT-LENGTH* . 10) (*PRINT-LEVEL* . 6) (*PRINT-PRETTY* . NIL))
</pre></div>

<p>The variables in the <code>car</code> positions are bound to the values in the <code>cdr</code>
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.
</p>
<p>Initially empty, <code>*debug-print-variable-alist*</code> is typically used to
provide bindings for printer control variables.
</p></dd></dl>

<hr>
<a name="Stack-Frames"></a>
<div class="header">
<p>
Next: <a href="#Variable-Access" accesskey="n" rel="next">Variable Access</a>, Previous: <a href="#Debugger-Command-Loop" accesskey="p" rel="prev">Debugger Command Loop</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Stack-Frames-1"></a>
<h3 class="section">5.3 Stack Frames</h3>
<a name="index-Stack-frames"></a>

<p>A <em>stack frame</em> 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:
</p>
<ul>
<li> <em>variables</em> (see <a href="#Variable-Access">Variable Access</a>), which are the values being operated
on.

</li><li> <em>arguments</em> to the call (which are really just particularly
interesting variables).

</li><li> a current source location (see <a href="#Source-Location-Printing">Source Location Printing</a>), 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.

</li></ul>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Stack-Motion" accesskey="1">Stack Motion</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#How-Arguments-are-Printed" accesskey="2">How Arguments are Printed</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Function-Names" accesskey="3">Function Names</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Debug-Tail-Recursion" accesskey="4">Debug Tail Recursion</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Unknown-Locations-and-Interrupts" accesskey="5">Unknown Locations and Interrupts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Stack-Motion"></a>
<div class="header">
<p>
Next: <a href="#How-Arguments-are-Printed" accesskey="n" rel="next">How Arguments are Printed</a>, Up: <a href="#Stack-Frames" accesskey="u" rel="up">Stack Frames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Stack-Motion-1"></a>
<h4 class="subsection">5.3.1 Stack Motion</h4>

<p>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:
</p>
<dl>
<dt><a name="index-up"></a>Debugger Command: <strong>up</strong></dt>
<dd><p>Move up to the next higher frame.  More recent function calls are
considered to be higher on the stack.
</p></dd></dl>

<dl>
<dt><a name="index-down"></a>Debugger Command: <strong>down</strong></dt>
<dd><p>Move down to the next lower frame.
</p></dd></dl>

<dl>
<dt><a name="index-top"></a>Debugger Command: <strong>top</strong></dt>
<dd><p>Move to the highest frame, that is, the frame where the debugger was
entered.
</p></dd></dl>

<dl>
<dt><a name="index-bottom"></a>Debugger Command: <strong>bottom</strong></dt>
<dd><p>Move to the lowest frame.
</p></dd></dl>

<dl>
<dt><a name="index-frame"></a>Debugger Command: <strong>frame</strong> <em>[<var>n</var>]</em></dt>
<dd><p>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.
</p></dd></dl>


<hr>
<a name="How-Arguments-are-Printed"></a>
<div class="header">
<p>
Next: <a href="#Function-Names" accesskey="n" rel="next">Function Names</a>, Previous: <a href="#Stack-Motion" accesskey="p" rel="prev">Stack Motion</a>, Up: <a href="#Stack-Frames" accesskey="u" rel="up">Stack Frames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-Arguments-are-Printed-1"></a>
<h4 class="subsection">5.3.2 How Arguments are Printed</h4>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(myfun (+ 3 4) 'a)
</pre></div>

<p>would look like this:
</p>
<div class="example">
<pre class="example">(MYFUN 7 A)
</pre></div>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(subseq &quot;foo&quot; 1)
</pre></div>

<p>would look like this:
</p>
<div class="example">
<pre class="example">(SUBSEQ &quot;foo&quot; 1 3)
</pre></div>

<p>And this call:
</p>
<div class="lisp">
<pre class="lisp">(string-upcase &quot;test case&quot;)
</pre></div>

<p>would look like this:
</p>
<div class="example">
<pre class="example">(STRING-UPCASE &quot;test case&quot; :START 0 :END NIL)
</pre></div>

<p>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.
</p>
<p><code>&amp;rest</code> arguments are handled somewhat differently.  The value of
the rest argument variable is displayed as the spread-out arguments to
the call, so:
</p>
<div class="lisp">
<pre class="lisp">(format t &quot;~A is a ~A.&quot; &quot;This&quot; 'test)
</pre></div>

<p>would look like this:
</p>
<div class="example">
<pre class="example">(FORMAT T &quot;~A is a ~A.&quot; &quot;This&quot; 'TEST)
</pre></div>

<p>Rest arguments cause an exception to the normal display of keyword
arguments in functions that have both <code>&amp;rest</code> and <code>&amp;key</code>
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.
</p>
<p>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 &lsquo;<samp>#&lt;unused-arg&gt;</samp>&rsquo; 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 (see <a href="#Variable-Access">Variable Access</a>),
then &lsquo;<samp>#&lt;unavailable-arg&gt;</samp>&rsquo; will be printed instead of the argument
value.
</p>
<p>Note that inline expansion and open-coding affect what frames
are present in the debugger, see <a href="#Debugger-Policy-Control">Debugger Policy Control</a>.
</p>

<hr>
<a name="Function-Names"></a>
<div class="header">
<p>
Next: <a href="#Debug-Tail-Recursion" accesskey="n" rel="next">Debug Tail Recursion</a>, Previous: <a href="#How-Arguments-are-Printed" accesskey="p" rel="prev">How Arguments are Printed</a>, Up: <a href="#Stack-Frames" accesskey="u" rel="up">Stack Frames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Function-Names-1"></a>
<h4 class="subsection">5.3.3 Function Names</h4>

<p>If a function is defined by <code>defun</code> it will appear in backtrace
by that name. Functions defined by <code>labels</code> and <code>flet</code> will
appear as <code>(FLET <var>name</var>)</code> and <code>(LABELS <var>name</var>)</code> respectively.
Anonymous lambdas will appear as <code>(LAMDBA <var>lambda-list</var>)</code>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Entry-Point-Details" accesskey="1">Entry Point Details</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Entry-Point-Details"></a>
<div class="header">
<p>
Up: <a href="#Function-Names" accesskey="u" rel="up">Function Names</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Entry-Point-Details-1"></a>
<h4 class="subsubsection">5.3.3.1 Entry Point Details</h4>
<a name="index-External-entry-points"></a>
<a name="index-Entry-points_002c-external"></a>
<a name="index-Block-compilation_002c-debugger-implications"></a>
<a name="index-External_002c-stack-frame-kind"></a>
<a name="index-Optional_002c-stack-frame-kind"></a>
<a name="index-Cleanup_002c-stack-frame-kind"></a>

<p>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.
</p>


<p>With recursive functions, an additional <code>external</code> 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 may also see <code>cleanup</code>
frames during the execution of <code>unwind-protect</code> cleanup code, and
<code>optional</code> for variable argument entry points.
</p>
<hr>
<a name="Debug-Tail-Recursion"></a>
<div class="header">
<p>
Next: <a href="#Unknown-Locations-and-Interrupts" accesskey="n" rel="next">Unknown Locations and Interrupts</a>, Previous: <a href="#Function-Names" accesskey="p" rel="prev">Function Names</a>, Up: <a href="#Stack-Frames" accesskey="u" rel="up">Stack Frames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debug-Tail-Recursion-1"></a>
<h4 class="subsection">5.3.4 Debug Tail Recursion</h4>
<a name="index-Tail-recursion"></a>
<a name="index-Recursion_002c-tail"></a>

<p>The compiler is &ldquo;properly tail recursive.&rdquo; If a function call is in
a tail-recursive position, the stack frame will be deallocated
<em>at the time of the call</em>, rather than after the call returns.
Consider this backtrace:
</p>
<div class="example">
<pre class="example">(BAR ...)
(FOO ...)
</pre></div>

<p>Because of tail recursion, it is not necessarily the case that
<code>FOO</code> directly called <code>BAR</code>.  It may be that <code>FOO</code>
called some other function <code>FOO2</code> which then called <code>BAR</code>
tail-recursively, as in this example:
</p>
<div class="lisp">
<pre class="lisp">(defun foo ()
  ...
  (foo2 ...)
  ...)

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

(defun bar (...)
  ...)
</pre></div>

<p>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.
See <a href="#Source-Location-Printing">Source Location Printing</a>.
</p>
<p>The elimination of tail-recursive frames can be prevented by disabling
tail-recursion optimization, which happens when the <code>debug</code>
optimization quality is greater than <code>2</code>.
See <a href="#Debugger-Policy-Control">Debugger Policy Control</a>.
</p>

<hr>
<a name="Unknown-Locations-and-Interrupts"></a>
<div class="header">
<p>
Previous: <a href="#Debug-Tail-Recursion" accesskey="p" rel="prev">Debug Tail Recursion</a>, Up: <a href="#Stack-Frames" accesskey="u" rel="up">Stack Frames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unknown-Locations-and-Interrupts-1"></a>
<h4 class="subsection">5.3.5 Unknown Locations and Interrupts</h4>
<a name="index-Unknown-code-locations"></a>
<a name="index-Locations_002c-unknown"></a>
<a name="index-Interrupts"></a>
<a name="index-Errors_002c-run_002dtime"></a>

<p>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
<em>unknown</em>.  If the code location for a frame is unknown, then some
variables may be inaccessible, and the source location cannot be
precisely displayed.
</p>
<p>There are three reasons why a code location could be unknown:
</p>
<ul>
<li> There is inadequate debug information due to the value of the <code>debug</code>
optimization quality.  See <a href="#Debugger-Policy-Control">Debugger Policy Control</a>.

</li><li> The debugger was entered because of an interrupt such as <tt class="key">C-c</tt>.

</li><li> A hardware error such as &ldquo;&lsquo;<samp>bus error</samp>&rsquo;&rdquo; occurred in code that was
compiled unsafely due to the value of the <code>safety</code> optimization
quality.

</li></ul>

<p>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, <a href="#Variable-Value-Availability">Variable Value Availability</a>.
</p>
<p>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&rsquo;t be
located.  If this happens, return from the interrupt and try again.
</p>

<hr>
<a name="Variable-Access"></a>
<div class="header">
<p>
Next: <a href="#Source-Location-Printing" accesskey="n" rel="next">Source Location Printing</a>, Previous: <a href="#Stack-Frames" accesskey="p" rel="prev">Stack Frames</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Variable-Access-1"></a>
<h3 class="section">5.4 Variable Access</h3>
<a name="index-Debug-variables"></a>
<a name="index-Variables_002c-debugger-access"></a>

<p>There are two ways to access the current frame&rsquo;s local variables in
the debugger: <code>list-locals</code> and <code>sb-debug:var</code>.
</p>
<p>The debugger doesn&rsquo;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.
</p>
<p>When there are ambiguous variables, the evaluator assigns each one a
small integer identifier.  The <code>sb-debug:var</code> function uses this
identifier to distinguish between ambiguous variables.  The
<code>list-locals</code> command prints the identifier.  In the
following example, there are two variables named <code>X</code>.  The first
one has identifier 0 (which is not printed), the second one has
identifier 1.
</p>
<div class="example">
<pre class="example">X  =  1
X#1  =  2
</pre></div>

<dl>
<dt><a name="index-list_002dlocals"></a>Debugger Command: <strong>list-locals</strong> <em>[<var>prefix</var>]</em></dt>
<dd><p>This command prints the name and value of all variables in the current
frame whose name has the specified <var>prefix</var>.  <var>prefix</var> may be
a string or a symbol.  If no <var>prefix</var> is given, then all available
variables are printed.  If a variable has a potentially ambiguous
name, then the name is printed with a &ldquo;<code>#<var>identifier</var></code>&rdquo;
suffix, where <var>identifier</var> is the small integer used to make the
name unique.
</p></dd></dl>

<dl>
<dt><a name="index-var"></a>Function: <strong>var</strong> <em>[sb-debug] <var>name</var> &amp;optional <var>identifier</var></em></dt>
<dd><p>This function returns the value of the variable in the current frame
with the specified <var>name</var>.  If supplied, <var>identifier</var>
determines which value to return when there are ambiguous variables.
</p>
<p>When <var>name</var> is a symbol, it is interpreted as the symbol name of
the variable, i.e. the package is significant.  If <var>name</var> is an
uninterned symbol (gensym), then return the value of the uninterned
variable with the same name.  If <var>name</var> is a string,
<code>sb-debug:var</code> interprets it as the prefix of a variable name
that must unambiguously complete to the name of a valid variable.
</p>
<p><var>identifier</var> is used to disambiguate the variable name; use
<code>list-locals</code> to find out the identifiers.
</p></dd></dl>


<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Variable-Value-Availability" accesskey="1">Variable Value Availability</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Note-On-Lexical-Variable-Access" accesskey="2">Note On Lexical Variable Access</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Variable-Value-Availability"></a>
<div class="header">
<p>
Next: <a href="#Note-On-Lexical-Variable-Access" accesskey="n" rel="next">Note On Lexical Variable Access</a>, Up: <a href="#Variable-Access" accesskey="u" rel="up">Variable Access</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Variable-Value-Availability-1"></a>
<h4 class="subsection">5.4.1 Variable Value Availability</h4>
<a name="index-Availability-of-debug-variables"></a>
<a name="index-Validity-of-debug-variables"></a>
<a name="index-Debug-optimization-quality"></a>

<p>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.
</p>
<p>The one exception is this: if you interrupt (e.g., with <tt class="key">C-c</tt>) or
if there is an unexpected hardware error such as &ldquo;&lsquo;<samp>bus error</samp>&rsquo;&rdquo;
(which should only happen in unsafe code), then the values displayed
for arguments to the interrupted frame might be
incorrect.<a name="DOCF4" href="#FOOT4"><sup>4</sup></a>  This exception applies only to the
interrupted frame: any frame farther down the stack will be fine.
</p>
<p>The value of a variable may be unavailable for these reasons:
</p>
<ul>
<li> The value of the <code>debug</code> 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
<code>debug</code> is at least <code>2</code>.

</li><li> 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 <code>debug</code> optimization quality is <code>3</code>.

</li><li> The variable&rsquo;s name is an uninterned symbol (gensym).  To save space, the
compiler only dumps debug information about uninterned variables when the
<code>debug</code> optimization quality is <code>3</code>.

</li><li> The frame&rsquo;s location is unknown (see <a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a>) 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.

</li><li> 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 <code>compilation-speed</code> optimization quality, but most
source-level optimizations are done under all compilation policies.

</li><li> The variable is never set and its definition looks like
<div class="lisp">
<pre class="lisp">(LET ((var1 var2))
   ...)
</pre></div>
<p>In this case, <code>var1</code> is substituted with <code>var2</code>.
</p>
</li><li> The variable is never set and is referenced exactly once.  In this
case, the reference is substituted with the variable initial value.

</li></ul>

<p>Since it is especially useful to be able to get the arguments to a
function, argument variables are treated specially when the
<code>speed</code> optimization quality is less than <code>3</code> and the
<code>debug</code> quality is at least <code>1</code>.  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, <code>debug</code> must be at least <code>2</code> for
values to be available, and even then, values are only available at
known locations.
</p>

<hr>
<a name="Note-On-Lexical-Variable-Access"></a>
<div class="header">
<p>
Previous: <a href="#Variable-Value-Availability" accesskey="p" rel="prev">Variable Value Availability</a>, Up: <a href="#Variable-Access" accesskey="u" rel="up">Variable Access</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Note-On-Lexical-Variable-Access-1"></a>
<h4 class="subsection">5.4.2 Note On Lexical Variable Access</h4>

<p>When the debugger command loop establishes variable bindings for
available variables, these variable bindings have lexical scope and
dynamic extent.<a name="DOCF5" href="#FOOT5"><sup>5</sup></a>  You can close
over them, but such closures can&rsquo;t be used as upward function arguments.
</p>
<p>You can also set local variables using <code>setq</code>, 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.
</p>

<hr>
<a name="Source-Location-Printing"></a>
<div class="header">
<p>
Next: <a href="#Debugger-Policy-Control" accesskey="n" rel="next">Debugger Policy Control</a>, Previous: <a href="#Variable-Access" accesskey="p" rel="prev">Variable Access</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Source-Location-Printing-1"></a>
<h3 class="section">5.5 Source Location Printing</h3>
<a name="index-Source-location-printing_002c-debugger"></a>

<p>One of the debugger&rsquo;s capabilities is source level debugging of
compiled code.  These commands display the source location for the
current frame:
</p>
<dl>
<dt><a name="index-source"></a>Debugger Command: <strong>source</strong> <em>[<var>context</var>]</em></dt>
<dd><p>This command displays the file that the current frame&rsquo;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 <var>context</var> is specified, then it is an integer
specifying the number of enclosing levels of list structure to print.
</p></dd></dl>

<p>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 <code>*some-random-special*</code>, then the innermost
enclosing evaluated form will be printed.  Here are some possible
enclosing forms:
</p>
<div class="lisp">
<pre class="lisp">(let ((a *some-random-special*))
  ...)

(+ *some-random-special* ...)
</pre></div>

<p>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
<samp>/usr/me/mystuff.lisp</samp> looked like this:
</p>
<div class="lisp">
<pre class="lisp">(defmacro mymac ()
  '(myfun))

(defun foo ()
  (mymac)
  ...)
</pre></div>

<p>If <code>foo</code> has called <code>myfun</code>, and is waiting for it to
return, then the <code>source</code> command would print:
</p>
<div class="example">
<pre class="example">; File: /usr/me/mystuff.lisp

(MYMAC)
</pre></div>

<p>Note that the macro use was printed, not the actual function call form,
<code>(myfun)</code>.
</p>
<p>If enclosing source is printed by giving an argument to
<code>source</code> or <code>vsource</code>, then the actual source form is
marked by wrapping it in a list whose first element is
&lsquo;<samp>#:***HERE***</samp>&rsquo;.  In the previous example, <code>source 1</code> would
print:
</p>
<div class="example">
<pre class="example">; File: /usr/me/mystuff.lisp

(DEFUN FOO ()
  (#:***HERE***
   (MYMAC))
  ...)
</pre></div>


<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#How-the-Source-is-Found" accesskey="1">How the Source is Found</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Source-Location-Availability" accesskey="2">Source Location Availability</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="How-the-Source-is-Found"></a>
<div class="header">
<p>
Next: <a href="#Source-Location-Availability" accesskey="n" rel="next">Source Location Availability</a>, Up: <a href="#Source-Location-Printing" accesskey="u" rel="up">Source Location Printing</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="How-the-Source-is-Found-1"></a>
<h4 class="subsection">5.5.1 How the Source is Found</h4>

<p>If the code was defined from Lisp by <code>compile</code> or
<code>eval</code>, then the source can always be reliably located.  If the
code was defined from a <samp>fasl</samp> file created by
<code>compile-file</code>, 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.
</p>
<p>The source file is opened using the <code>truename</code> 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&rsquo;t
be located using this name, then the debugger gives up and signals an
error.
</p>
<p>If the source file can be found, but has been modified since the time it was
compiled, the debugger prints this warning:
</p>
<div class="example">
<pre class="example">; File has been modified since compilation:
;   <var>filename</var>
; Using form offset instead of character position.
</pre></div>

<p>where <var>filename</var> 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:
</p>
<ul>
<li> No top-level forms before the top-level form containing the source
have been added or deleted, and

</li><li> 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.)

</li></ul>

<p>If the heuristic doesn&rsquo;t work, the displayed source will be wrong, but will
probably be near the actual source.  If the &ldquo;shape&rdquo; 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.
</p>
<p>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
<code>eq</code> list twice.  If you don&rsquo;t define read macros and don&rsquo;t use
<code>##</code> in perverted ways, you don&rsquo;t need to worry about this.
</p>

<hr>
<a name="Source-Location-Availability"></a>
<div class="header">
<p>
Previous: <a href="#How-the-Source-is-Found" accesskey="p" rel="prev">How the Source is Found</a>, Up: <a href="#Source-Location-Printing" accesskey="u" rel="up">Source Location Printing</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Source-Location-Availability-1"></a>
<h4 class="subsection">5.5.2 Source Location Availability</h4>
<a name="index-Debug-optimization-quality-1"></a>
<a name="index-Block_002c-basic"></a>
<a name="index-Block_002c-start-location"></a>

<p>Source location information is only available when the <code>debug</code>
optimization quality is at least <code>2</code>.  If source location
information is unavailable, the source commands will give an error
message.
</p>
<p>If source location information is available, but the source location
is unknown because of an interrupt or unexpected hardware error
(see <a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a>), then the command will
print:
</p>
<div class="example">
<pre class="example">Unknown location: using block start.
</pre></div>

<p>and then proceed to print the source location for the start of the
<em>basic block</em> enclosing the code location.  It&rsquo;s a bit
complicated to explain exactly what a basic block is, but here are
some properties of the block start location:
</p>
<ul>
<li> The block start location may be the same as the true location.

</li><li> The block start location will never be later in the
program&rsquo;s flow of control than the true location.

</li><li> No conditional control structures (such as <code>if</code>,
<code>cond</code>, <code>or</code>) 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 <em>do not</em> end
basic blocks.

</li><li> The head of a loop will be the start of a block.

</li><li> The programming language concept of &ldquo;block structure&rdquo; and the
Lisp <code>block</code> special form are totally unrelated to the compiler&rsquo;s
basic block.

</li></ul>

<p>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.)
</p>

<hr>
<a name="Debugger-Policy-Control"></a>
<div class="header">
<p>
Next: <a href="#Exiting-Commands" accesskey="n" rel="next">Exiting Commands</a>, Previous: <a href="#Source-Location-Printing" accesskey="p" rel="prev">Source Location Printing</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Debugger-Policy-Control-1"></a>
<h3 class="section">5.6 Debugger Policy Control</h3>
<a name="index-Policy_002c-debugger"></a>
<a name="index-Debug-optimization-quality-2"></a>
<a name="index-Optimize-declaration"></a>
<a name="index-Inline-expansion-1"></a>
<a name="index-Semi_002dinline-expansion"></a>

<p>The compilation policy specified by <code>optimize</code> declarations
affects the behavior seen in the debugger.  The <code>debug</code> 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.
</p>
<p>Unlike the other optimization qualities (which are compared in relative value
to evaluate tradeoffs), the <code>debug</code> 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 <code>debug</code> quality:
</p>
<dl compact="compact">
<dt><code>0</code></dt>
<dd><p>Only the function name and enough information to allow the stack to
be parsed.
</p>
</dd>
<dt><code>&gt; 0</code></dt>
<dd><p>Any level greater than <code>0</code> gives level <code>0</code> plus all argument
variables.  Values will only be accessible if the argument variable is
never set and <code>speed</code> is not <code>3</code>.  SBCL allows any real
value for optimization qualities.  It may be useful to specify
<code>0.5</code> to get backtrace argument display without argument
documentation.
</p>
</dd>
<dt><code>1</code></dt>
<dd><p>Level <code>1</code> provides argument documentation (printed argument lists) and
derived argument/result type information.  This makes <code>describe</code>
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.
</p>
</dd>
<dt><code>2</code></dt>
<dd><p>Level <code>1</code> plus all interned local variables, source location
information, and lifetime information that tells the debugger when
arguments are available (even when <code>speed</code> is <code>3</code> or the
argument is set).
</p>
</dd>
<dt><code>&gt; 2</code></dt>
<dd><p>Any level greater than <code>2</code> gives level <code>2</code> and in addition
disables tail-call optimization, so that the backtrace will contain
frames for all invoked functions, even those in tail positions.
</p>
</dd>
<dt><code>3</code></dt>
<dd><p>Level <code>2</code> plus all uninterned variables.  In addition, lifetime
analysis is disabled (even when <code>speed</code> is <code>3</code>), 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.
</p>
</dd>
<dt><code>&gt; (max speed space)</code></dt>
<dd><p>If <code>debug</code> is greater than both <code>speed</code> and <code>space</code>,
the command <code>return</code> can be used to continue execution by
returning a value from the current stack frame.
</p>
</dd>
<dt><code>&gt; (max speed space compilation-speed)</code></dt>
<dd><p>If <code>debug</code> is greater than all of <code>speed</code>, <code>space</code> and
<code>compilation-speed</code> the code will be steppable (see <a href="#Single-Stepping">Single Stepping</a>).
</p>
</dd>
</dl>

<p>As you can see, if the <code>speed</code> quality is <code>3</code>, debugger performance is
degraded.  This effect comes from the elimination of argument variable
special-casing (see <a href="#Variable-Value-Availability">Variable Value Availability</a>).  Some degree of
speed/debuggability tradeoff is unavoidable, but the effect is not too drastic
when <code>debug</code> is at least <code>2</code>.
</p>
<p>In addition to <code>inline</code> and <code>notinline</code> declarations, the
relative values of the <code>speed</code> and <code>space</code> 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
&ldquo;semi-inline&rdquo;, 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.
</p>

<hr>
<a name="Exiting-Commands"></a>
<div class="header">
<p>
Next: <a href="#Information-Commands" accesskey="n" rel="next">Information Commands</a>, Previous: <a href="#Debugger-Policy-Control" accesskey="p" rel="prev">Debugger Policy Control</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Exiting-Commands-1"></a>
<h3 class="section">5.7 Exiting Commands</h3>

<p>These commands get you out of the debugger.
</p>
<dl>
<dt><a name="index-toplevel"></a>Debugger Command: <strong>toplevel</strong></dt>
<dd><p>Throw to top level.
</p></dd></dl>

<dl>
<dt><a name="index-restart"></a>Debugger Command: <strong>restart</strong> <em>[<var>n</var>]</em></dt>
<dd><p>Invokes the <var>n</var>th restart case as displayed by the <code>error</code>
command.  If <var>n</var> is not specified, the available restart cases are
reported.
</p></dd></dl>

<dl>
<dt><a name="index-continue"></a>Debugger Command: <strong>continue</strong></dt>
<dd><p>Calls <code>continue</code> on the condition given to <code>debug</code>.  If there is no
restart case named <var>continue</var>, then an error is signaled.
</p></dd></dl>

<dl>
<dt><a name="index-abort"></a>Debugger Command: <strong>abort</strong></dt>
<dd><p>Calls <code>abort</code> on the condition given to <code>debug</code>.  This is
useful for popping debug command loop levels or aborting to top level,
as the case may be.
</p></dd></dl>

<dl>
<dt><a name="index-return"></a>Debugger Command: <strong>return</strong> <em><var>value</var></em></dt>
<dd><p>Returns <var>value</var> from the current stack frame.  This command is
available when the <code>debug</code> optimization quality is greater than
both <code>speed</code> and <code>space</code>.  Care must be taken that the value
is of the same type as SBCL expects the stack frame to return.
</p></dd></dl>

<dl>
<dt><a name="index-restart_002dframe"></a>Debugger Command: <strong>restart-frame</strong></dt>
<dd><p>Restarts execution of the current stack frame. This command is
available when the <code>debug</code> optimization quality is greater than
both <code>speed</code> and <code>space</code> 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.
</p></dd></dl>

<hr>
<a name="Information-Commands"></a>
<div class="header">
<p>
Next: <a href="#Function-Tracing" accesskey="n" rel="next">Function Tracing</a>, Previous: <a href="#Exiting-Commands" accesskey="p" rel="prev">Exiting Commands</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Information-Commands-1"></a>
<h3 class="section">5.8 Information Commands</h3>

<p>Most of these commands print information about the current frame or
function, but a few show general information.
</p>
<dl>
<dt><a name="index-help"></a>Debugger Command: <strong>help</strong></dt>
<dt><a name="index-_003f"></a>Debugger Command: <strong>?</strong></dt>
<dd><p>Displays a synopsis of debugger commands.
</p></dd></dl>

<dl>
<dt><a name="index-describe"></a>Debugger Command: <strong>describe</strong></dt>
<dd><p>Calls <code>describe</code> on the current function and displays the number of
local variables.
</p></dd></dl>

<dl>
<dt><a name="index-print"></a>Debugger Command: <strong>print</strong></dt>
<dd><p>Displays the current function call as it would be displayed by moving to
this frame.
</p></dd></dl>

<dl>
<dt><a name="index-error"></a>Debugger Command: <strong>error</strong></dt>
<dd><p>Prints the condition given to <code>invoke-debugger</code> and the active
proceed cases.
</p></dd></dl>

<dl>
<dt><a name="index-backtrace"></a>Debugger Command: <strong>backtrace</strong> <em>[<var>n</var>]</em></dt>
<dd><p>Displays all the frames from the current to the bottom. Only shows
<var>n</var> frames if specified. The printing is controlled by
<code>*debug-print-variable-alist*</code>.
</p></dd></dl>

































<hr>
<a name="Function-Tracing"></a>
<div class="header">
<p>
Next: <a href="#Single-Stepping" accesskey="n" rel="next">Single Stepping</a>, Previous: <a href="#Information-Commands" accesskey="p" rel="prev">Information Commands</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Function-Tracing-1"></a>
<h3 class="section">5.9 Function Tracing</h3>
<a name="index-Tracing"></a>
<a name="index-Function_002c-tracing"></a>

<p>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.
</p>
<a name="Macro-common_002dlisp_003atrace"></a><dl>
<dt><a name="index-trace"></a>Macro: <strong>trace</strong> <em>[cl] &amp;rest specs</em></dt>
<dd><p><code>trace</code> {Option Global-Value}* {Name {Option Value}*}*
</p>
<p><code>trace</code> is a debugging tool that provides information when specified
functions are called. In its simplest form:
</p>
<div class="lisp">
<pre class="lisp">       (TRACE NAME-1 NAME-2 ...)
</pre></div>

<p>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.
</p>
<p>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 <code>trace</code>. 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.
</p>
<p>By default, <code>trace</code> causes a printout on <code>*trace-output*</code> each time that
one of the named functions is entered or returns. (This is the basic,
<code>ansi</code> Common Lisp behavior of <code>trace</code>.)
</p>
<p>The following options are defined:
</p>

<dl compact="compact">
<dt><em><code>:report</code> Report-Type</em></dt>
<dd><p>If Report-Type is <code>trace</code> (the default) then information is
       reported by printing immediately. If Report-Type is <code>nil</code>, then
       the only effect of the trace is to execute other
       options (e.g. <code>print</code> or BREAK).
</p>

</dd>
<dt><em><code>:condition</code> Form</em></dt>
<dt><em><code>:condition-after</code> Form</em></dt>
<dt><em><code>:condition-all</code> Form</em></dt>
<dd><p>If <code>:condition</code> is specified, then <code>trace</code> does nothing unless Form
       evaluates to true at the time of the call. <code>:condition-after</code> is
       similar, but suppresses the initial printout, and is tested when the
       function returns. <code>:condition-all</code> tries both before and after.
</p>

</dd>
<dt><em><code>:break</code> Form</em></dt>
<dt><em><code>:break-after</code> Form</em></dt>
<dt><em><code>:break-all</code> Form</em></dt>
<dd><p>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.
</p>

</dd>
<dt><em><code>:print</code> Form</em></dt>
<dt><em><code>:print-after</code> Form</em></dt>
<dt><em><code>:print-all</code> Form</em></dt>
<dd><p>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.
</p>

</dd>
<dt><em><code>:wherein</code> Names</em></dt>
<dd><p>If specified, Names is a function name or list of names. <code>trace</code> 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 &quot;DEFUN FOO&quot;.
</p>

</dd>
<dt><em><code>:encapsulate</code> {:DEFAULT | <code>t</code> | NIL}</em></dt>
<dd><p>If <code>t</code>, the tracing is done via encapsulation (redefining the function
       name) rather than by modifying the function. <code>:default</code> 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&rsquo;s lexical environment, but <code>sb-debug:arg</code>
       can still be used.
</p>

</dd>
<dt><em><code>:methods</code> {T | NIL}</em></dt>
<dd><p>If <code>t</code>, any function argument naming a generic function will have its
       methods traced in addition to the generic function itself.
</p>

</dd>
<dt><em><code>:function</code> Function-Form</em></dt>
<dd><p>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 traced.
</p>
</dd>
</dl>

<p><code>:condition</code>, <code>:break</code> and <code>:print</code> forms are evaluated in a context which
mocks up the lexical environment of the called function, so that
<code>sb-debug:var</code> and <code>sb-debug:arg</code> can be used.
The <code>-after</code> and <code>-all</code> forms can use <code>sb-debug:arg</code>.
</p></dd></dl>

<a name="Macro-common_002dlisp_003auntrace"></a><dl>
<dt><a name="index-untrace"></a>Macro: <strong>untrace</strong> <em>[cl] &amp;rest specs</em></dt>
<dd><p>Remove tracing from the specified functions. Untraces all
functions when called with no arguments.
</p></dd></dl>

<a name="Variable-sb_002ddebug_003a_002atrace_002dindentation_002dstep_002a"></a><dl>
<dt><a name="index-_002atrace_002dindentation_002dstep_002a"></a>Variable: <strong>*trace-indentation-step*</strong> <em>[sb-debug]</em></dt>
<dd><p>the increase in trace indentation at each call level
</p></dd></dl>

<a name="Variable-sb_002ddebug_003a_002amax_002dtrace_002dindentation_002a"></a><dl>
<dt><a name="index-_002amax_002dtrace_002dindentation_002a"></a>Variable: <strong>*max-trace-indentation*</strong> <em>[sb-debug]</em></dt>
<dd><p>If the trace indentation exceeds this value, then indentation restarts at
   0.
</p></dd></dl>

<a name="Variable-sb_002ddebug_003a_002atrace_002dencapsulate_002ddefault_002a"></a><dl>
<dt><a name="index-_002atrace_002dencapsulate_002ddefault_002a"></a>Variable: <strong>*trace-encapsulate-default*</strong> <em>[sb-debug]</em></dt>
<dd><p>the default value for the <code>:encapsulate</code> option to <code>trace</code>
</p></dd></dl>


<hr>
<a name="Single-Stepping"></a>
<div class="header">
<p>
Next: <a href="#Enabling-and-Disabling-the-Debugger" accesskey="n" rel="next">Enabling and Disabling the Debugger</a>, Previous: <a href="#Function-Tracing" accesskey="p" rel="prev">Function Tracing</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Single-Stepping-1"></a>
<h3 class="section">5.10 Single Stepping</h3>
<a name="index-Stepper"></a>
<a name="index-Single-Stepping"></a>

<p>SBCL includes an instrumentation based single-stepper for compiled
code, that can be invoked via the <code>step</code> macro, or from within
the debugger. See <a href="#Debugger-Policy-Control">Debugger Policy Control</a>, for details on enabling
stepping for compiled code.
</p>
<p>The following debugger commands are used for controlling single stepping.
</p>
<dl>
<dt><a name="index-start"></a>Debugger Command: <strong>start</strong></dt>
<dd><p>Selects the <code>continue</code> 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 <code>start</code> or by using the standard
<code>step</code> macro.
</p></dd></dl>

<dl>
<dt><a name="index-step"></a>Debugger Command: <strong>step</strong></dt>
<dd><p>Steps into the current form. Stepping will be resumed when the next
form that has been compiled with stepper instrumentation is evaluated.
</p></dd></dl>

<dl>
<dt><a name="index-next"></a>Debugger Command: <strong>next</strong></dt>
<dd><p>Steps over the current form. Stepping will be disabled until evaluation of
the form is complete.
</p></dd></dl>

<dl>
<dt><a name="index-out"></a>Debugger Command: <strong>out</strong></dt>
<dd><p>Steps out of the current frame. Stepping will be disabled until the
topmost stack frame that had been stepped into returns.
</p></dd></dl>

<dl>
<dt><a name="index-stop"></a>Debugger Command: <strong>stop</strong></dt>
<dd><p>Stops the single stepper and resumes normal execution.
</p></dd></dl>

<a name="Macro-common_002dlisp_003astep"></a><dl>
<dt><a name="index-step-1"></a>Macro: <strong>step</strong> <em>[cl] form</em></dt>
<dd><p>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 <code>debug</code> policy
to be at least partially steppable.
</p></dd></dl>

<hr>
<a name="Enabling-and-Disabling-the-Debugger"></a>
<div class="header">
<p>
Previous: <a href="#Single-Stepping" accesskey="p" rel="prev">Single Stepping</a>, Up: <a href="#Debugger" accesskey="u" rel="up">Debugger</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Enabling-and-Disabling-the-Debugger-1"></a>
<h3 class="section">5.11 Enabling and Disabling the Debugger</h3>

<a name="index-debugger_002c-enabling"></a>
<a name="index-debugger_002c-disabling"></a>
<a name="index-disabling-debugger"></a>
<a name="index-ldb_002c-enabling"></a>
<a name="index-ldb_002c-disabling-1"></a>
<a name="index-disabling-ldb-1"></a>

<p>In certain contexts (e.g., non-interactive applications), it may be
desirable to turn off the SBCL debugger (and possibly re-enable it).
The functions here control the debugger.
</p>
<a name="Function-sb_002dext_003adisable_002ddebugger"></a><dl>
<dt><a name="index-disable_002ddebugger"></a>Function: <strong>disable-debugger</strong> <em>[sb-ext]</em></dt>
<dd><p>When invoked, this function will turn off both the <code>sbcl</code> debugger
and <code>ldb</code> (the low-level debugger).  See also <code>enable-debugger</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aenable_002ddebugger"></a><dl>
<dt><a name="index-enable_002ddebugger"></a>Function: <strong>enable-debugger</strong> <em>[sb-ext]</em></dt>
<dd><p>Restore the debugger if it has been turned off by <code>disable-debugger</code>.
</p></dd></dl>
<hr>
<a name="Efficiency"></a>
<div class="header">
<p>
Next: <a href="#Beyond-the-ANSI-Standard" accesskey="n" rel="next">Beyond the ANSI Standard</a>, Previous: <a href="#Debugger" accesskey="p" rel="prev">Debugger</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Efficiency-1"></a>
<h2 class="chapter">6 Efficiency</h2>
<a name="index-Efficiency"></a>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Slot-access" accesskey="1">Slot access</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Dynamic_002dextent-allocation" accesskey="2">Dynamic-extent allocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Modular-arithmetic" accesskey="3">Modular arithmetic</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Global-and-Always_002dBound-variables" accesskey="4">Global and Always-Bound variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-Efficiency-Issues" accesskey="5">Miscellaneous Efficiency Issues</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Slot-access"></a>
<div class="header">
<p>
Next: <a href="#Dynamic_002dextent-allocation" accesskey="n" rel="next">Dynamic-extent allocation</a>, Up: <a href="#Efficiency" accesskey="u" rel="up">Efficiency</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Slot-access-1"></a>
<h3 class="section">6.1 Slot access</h3>
<a name="index-Slot-access"></a>

<a name="Structure-object-slot-access"></a>
<h4 class="subsection">6.1.1 Structure object slot access</h4>

<p>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 <code>notinline</code>, or passing
it as a functional argument to another function causes severe
performance degradation.
</p>
<a name="Standard-object-slot-access"></a>
<h4 class="subsection">6.1.2 Standard object slot access</h4>

<p>The most efficient way to access a slot of a <code>standard-object</code> is
by using <code>slot-value</code> with a constant slot name argument inside a
<code>defmethod</code> 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.
</p>
<p>Second most efficient way is to use a CLOS slot accessor, or
<code>slot-value</code> 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.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">(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))
</pre></div>

<p>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.
</p>
<hr>
<a name="Dynamic_002dextent-allocation"></a>
<div class="header">
<p>
Next: <a href="#Modular-arithmetic" accesskey="n" rel="next">Modular arithmetic</a>, Previous: <a href="#Slot-access" accesskey="p" rel="prev">Slot access</a>, Up: <a href="#Efficiency" accesskey="u" rel="up">Efficiency</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Dynamic_002dextent-allocation-1"></a>
<h3 class="section">6.2 Dynamic-extent allocation</h3>
<a name="index-dynamic_002dextent-declaration"></a>
<a name="index-declaration_002c-dynamic_002dextent"></a>

<p>SBCL has fairly extensive support for performing allocation on the
stack when a variable is declared <code>dynamic-extent</code>. The
<code>dynamic-extent</code> declarations are not verified, but are simply
trusted as long as <code>sb-ext:*stack-allocate-dynamic-extent*</code> is
true.
</p>
<a name="Variable-sb_002dext_003a_002astack_002dallocate_002ddynamic_002dextent_002a"></a><dl>
<dt><a name="index-_002astack_002dallocate_002ddynamic_002dextent_002a"></a>Variable: <strong>*stack-allocate-dynamic-extent*</strong> <em>[sb-ext]</em></dt>
<dd><p>If true (the default), the compiler respects <code>dynamic-extent</code> 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 <code>safety</code> code, as such a vector could overflow
the stack without triggering overflow protection.
</p></dd></dl>

<p>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.
</p>
<p>In particular, it is important to realize that dynamic extend is
contagious:
</p>
<div class="lisp">
<pre class="lisp">(let* ((a (list 1 2 3))
       (b (cons a a)))
   (declare (dynamic-extent b))
   ;; Unless A is accessed elsewhere as well, SBCL will consider
   ;; it to be otherwise inaccessible -- it can only be accessed
   ;; through B, after all -- and stack allocate it as well.
   ;;
   ;; Hence returning (CAR B) here is unsafe.
   ...)
</pre></div>

<p>This allows stack allocation of complex structures. As a notable
exception to this, SBCL does not as of 1.0.48.21 propagate
dynamic-extentness through <code>&amp;rest</code> arguments &ndash; but another
conforming implementation might, so portable code should not rely on
this.
</p>
<div class="lisp">
<pre class="lisp">(declaim (inline foo))
(defun foo (fun &amp;rest arguments)
  (declare (dynamic-extent arguments))
  (apply fun arguments))

(defun bar (a)
  ;; SBCL will heap allocate the result of (LIST A), and stack allocate
  ;; only the spine of the &amp;rest list -- so this is safe, but unportable.
  ;;
  ;; Another implementation, including earlier versions of SBCL might consider
  ;; (LIST A) to be otherwise inaccessible and stack-allocate it as well!
  (foo #'car (list a)))
</pre></div>

<p>There are many cases when <code>dynamic-extent</code> declarations could be
useful. At present, SBCL implements stack allocation for
</p>
<ul>
<li> <code>&amp;rest</code> lists, when these are declared <code>dynamic-extent</code>.

</li><li> <a name="index-cons-_005bcl_005d"></a>
<a name="index-list-_005bcl_005d"></a>
<a name="index-list_002a-_005bcl_005d"></a>
<a name="index-vector-_005bcl_005d"></a>
<code>cons</code>, <code>list</code>, <code>list*</code>, and <code>vector</code> when the
result is bound to a variable declared <code>dynamic-extent</code>.

</li><li> <a name="index-make_002darray-_005bcl_005d"></a>
simple forms of <code>make-array</code>, whose result is bound to a variable
declared <code>dynamic-extent</code>: stack allocation is possible only if
the resulting array is known to be both simple and one-dimensional,
and has a constant <code>:element-type</code>.

<a name="index-Safety-optimization-quality-1"></a>
<p><strong>Note</strong>: 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 <code>safety</code> policies.
</p>
</li><li> <a name="index-flet-_005bcl_005d"></a>
<a name="index-labels-_005bcl_005d"></a>
<a name="index-safety-optimization-quality"></a>
<a name="index-optimization-quality_002c-safety"></a>
closures defined with <code>flet</code> or <code>labels</code>, with a bound
<code>dynamic-extent</code> declaration. Blocks and tags are also allocated
on the heap, unless all non-local control transfers to them are
compiled with zero <code>safety</code>.

</li><li> user-defined structures when the structure constructor defined using
<code>defstruct</code> has been declared <code>inline</code> and the result of the
call to the constructor is bound to a variable declared
<code>dynamic-extent</code>.

<p><strong>Note</strong>: structures with &ldquo;raw&rdquo; slots can currently be
stack-allocated only on x86 and x86-64.
</p>
</li><li> all of the above when they appear as initial parts of another
stack-allocated object.

</li></ul>

<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">;;; 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 &amp;REST lists
(defun foo (&amp;rest args)
  (declare (dynamic-extent args))
  ...)
</pre></div>

<p>Future plans include
</p>
<ul>
<li> Automatic detection of the common idiom of calling quantifiers with a
closure, even when the closure is not declared <code>dynamic-extent</code>.

</li></ul>

<hr>
<a name="Modular-arithmetic"></a>
<div class="header">
<p>
Next: <a href="#Global-and-Always_002dBound-variables" accesskey="n" rel="next">Global and Always-Bound variables</a>, Previous: <a href="#Dynamic_002dextent-allocation" accesskey="p" rel="prev">Dynamic-extent allocation</a>, Up: <a href="#Efficiency" accesskey="u" rel="up">Efficiency</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Modular-arithmetic-1"></a>
<h3 class="section">6.3 Modular arithmetic</h3>
<a name="index-Modular-arithmetic"></a>
<a name="index-Arithmetic_002c-modular"></a>
<a name="index-Arithmetic_002c-hardware"></a>
<a name="index-logand-_005bcl_005d"></a>
<p>Some numeric functions have a property: <var>N</var> lower bits of the
result depend only on <var>N</var> lower bits of (all or some)
arguments. If the compiler sees an expression of form <code>(logand
<var>exp</var> <var>mask</var>)</code>, where <var>exp</var> is a tree of such &ldquo;good&rdquo;
functions and <var>mask</var> is known to be of type <code>(unsigned-byte
<var>w</var>)</code>, where <var>w</var> is a &ldquo;good&rdquo; width, all intermediate results
will be cut to <var>w</var> bits (but it is not done for variables and
constants!). This often results in an ability to use simple machine
instructions for the functions.
</p>
<p>Consider an example.
</p>
<div class="lisp">
<pre class="lisp">(defun i (x y)
  (declare (type (unsigned-byte 32) x y))
  (ldb (byte 32 0) (logxor x (lognot y))))
</pre></div>

<p>The result of <code>(lognot y)</code> will be negative and of type
<code>(signed-byte 33)</code>, 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 <code>logxor</code> and <code>lognot</code>
with versions cutting results to 32 bits, and because terminals
(here&mdash;expressions <code>x</code> and <code>y</code>) are also of type
<code>(unsigned-byte 32)</code>, 32-bit machine arithmetic can be used.
</p>
<p>As of SBCL 0.8.5 &ldquo;good&rdquo; functions are <code>+</code>, <code>-</code>;
<code>logand</code>, <code>logior</code>, <code>logxor</code>, <code>lognot</code> and their
combinations; and <code>ash</code> with the positive second
argument. &ldquo;Good&rdquo; 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.
</p>
<hr>
<a name="Global-and-Always_002dBound-variables"></a>
<div class="header">
<p>
Next: <a href="#Miscellaneous-Efficiency-Issues" accesskey="n" rel="next">Miscellaneous Efficiency Issues</a>, Previous: <a href="#Modular-arithmetic" accesskey="p" rel="prev">Modular arithmetic</a>, Up: <a href="#Efficiency" accesskey="u" rel="up">Efficiency</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Global-and-Always_002dBound-variables-1"></a>
<h3 class="section">6.4 Global and Always-Bound variables</h3>

<a name="Macro-sb_002dext_003adefglobal"></a><dl>
<dt><a name="index-defglobal"></a>Macro: <strong>defglobal</strong> <em>[sb-ext] name value &amp;optional doc</em></dt>
<dd><p>Defines <code>name</code> as a global variable that is always bound. <code>value</code> is evaluated
and assigned to <code>name</code> both at compile- and load-time, but only if <code>name</code> is not
already bound.
</p>
<p>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.
</p>
<p>See also the declarations <code>sb-ext:global</code> and <code>sb-ext:always-bound</code>.
</p></dd></dl>

<dl>
<dt><a name="index-global"></a>Declaration: <strong>global</strong> <em>[sb-ext]</em></dt>
<dd>
<p>Syntax: <code>(sb-ext:global symbol*)</code>
</p>
<p>Only valid as a global proclamation.
</p>
<p>Specifies that the named symbols cannot be proclaimed or locally
declared <code>special</code>. Proclaiming an already special or constant
variable name as <code>global</code> signal an error. Allows more efficient
value lookup in threaded environments in addition to expressing
programmer intention.
</p></dd></dl>

<dl>
<dt><a name="index-always_002dbound"></a>Declaration: <strong>always-bound</strong> <em>[sb-ext]</em></dt>
<dd>
<p>Syntax: <code>(sb-ext:always-bound symbol*)</code>
</p>
<p>Only valid as a global proclamation.
</p>
<p>Specifies that the named symbols are always bound. Inhibits
<code>makunbound</code> of the named symbols. Proclaiming an unbound symbol
as <code>always-bound</code> signals an error. Allows the compiler to elide
boundness checks from value lookups.
</p></dd></dl>

<hr>
<a name="Miscellaneous-Efficiency-Issues"></a>
<div class="header">
<p>
Previous: <a href="#Global-and-Always_002dBound-variables" accesskey="p" rel="prev">Global and Always-Bound variables</a>, Up: <a href="#Efficiency" accesskey="u" rel="up">Efficiency</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Miscellaneous-Efficiency-Issues-1"></a>
<h3 class="section">6.5 Miscellaneous Efficiency Issues</h3>

<p>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
</p>
<ul>
<li> Advanced Compiler Use and Efficiency Hints
</li><li> Advanced Compiler Introduction
</li><li> More About Types in Python
</li><li> Type Inference
</li><li> Source Optimization
</li><li> Tail Recursion
</li><li> Local Call
</li><li> Block Compilation
</li><li> Inline Expansion
</li><li> Object Representation
</li><li> Numbers
</li><li> General Efficiency Hints
</li><li> Efficiency Notes
</li></ul>

<p>Besides this information from the CMUCL manual, there are a few other
points to keep in mind.
</p>
<ul>
<li> <a name="index-let-_005bcl_005d"></a>
<a name="index-let_002a-_005bcl_005d"></a>
<a name="index-setq-_005bcl_005d"></a>
<a name="index-setf-_005bcl_005d"></a>
The CMUCL manual doesn&rsquo;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 <code>let</code>, <code>let*</code>, inline function call, and so
forth. However, it&rsquo;s much more passive and dumb about inferring the
types of values assigned with <code>setq</code>, <code>setf</code>, and
friends. It would be nice to fix this, but in the meantime don&rsquo;t
expect that just because it&rsquo;s very smart about types in most respects
it will be smart about types involved in assignments.  (This doesn&rsquo;t
affect its ability to benefit from explicit type declarations
involving the assigned variables, only its ability to get by without
explicit type declarations.)


</li><li> 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&rsquo;t discussed in the CMUCL manual. (Some new material should be
written about this.)

</li><li> SBCL has some important known efficiency problems.  Perhaps the most
important are

<ul class="no-bullet">
<li>- The garbage collector is not particularly efficient, at least on
platforms without the generational collector (as of SBCL 0.8.9, all
except x86).

</li><li>- Various aspects of the PCL implementation of CLOS are more inefficient
than necessary.

</li></ul>

</li></ul>

<p>Finally, note that Common Lisp defines many constructs which, in
the infamous phrase, &ldquo;could be compiled efficiently by a
sufficiently smart compiler&rdquo;. 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&rsquo;re optimized on a
case-by-case basis by hand-written code, or not optimized at all if
the appropriate case hasn&rsquo;t been hand-coded. Some cases where no such
hand-coding has been done as of SBCL version 0.6.3 include
</p>
<ul>
<li> <code>(reduce #'f x)</code> where the type of <code>x</code> is known at compile
time

</li><li> various bit vector operations, e.g.  <code>(position 0
some-bit-vector)</code>

</li><li> specialized sequence idioms, e.g.  <code>(remove item list :count 1)</code>

</li><li> cases where local compilation policy does not require excessive type
checking, e.g.  <code>(locally (declare (safety 1)) (assoc item
list))</code> (which currently performs safe <code>endp</code> checking internal
to assoc).

</li></ul>

<p>If your system&rsquo;s performance is suffering because of some construct
which could in principle be compiled efficiently, but which the SBCL
compiler can&rsquo;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 &ldquo;<code>deftransform</code>&rdquo; to find many
examples (some straightforward, some less so).
</p><hr>
<a name="Beyond-the-ANSI-Standard"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Function-Interface" accesskey="n" rel="next">Foreign Function Interface</a>, Previous: <a href="#Efficiency" accesskey="p" rel="prev">Efficiency</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Beyond-the-ANSI-Standard-1"></a>
<h2 class="chapter">7 Beyond the ANSI Standard</h2>

<p>SBCL is derived from CMUCL, which implements many extensions to the
ANSI standard. SBCL doesn&rsquo;t support as many extensions as CMUCL, but
it still has quite a few.  See <a href="#Contributed-Modules">Contributed Modules</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Reader-Extensions" accesskey="1">Reader Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package_002dLocal-Nicknames" accesskey="2">Package-Local Nicknames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package-Variance" accesskey="3">Package Variance</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Garbage-Collection" accesskey="4">Garbage Collection</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Metaobject-Protocol" accesskey="5">Metaobject Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Extensible-Sequences" accesskey="6">Extensible Sequences</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Support-For-Unix" accesskey="7">Support For Unix</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Unicode-Support" accesskey="8">Unicode Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Customization-Hooks-for-Users" accesskey="9">Customization Hooks for Users</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Tools-To-Help-Developers">Tools To Help Developers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Resolution-of-Name-Conflicts">Resolution of Name Conflicts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Hash-Table-Extensions">Hash Table Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Random-Number-Generation">Random Number Generation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Stale-Extensions">Stale Extensions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Efficiency-Hacks">Efficiency Hacks</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Reader-Extensions"></a>
<div class="header">
<p>
Next: <a href="#Package_002dLocal-Nicknames" accesskey="n" rel="next">Package-Local Nicknames</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Reader-Extensions-1"></a>
<h3 class="section">7.1 Reader Extensions</h3>
<a name="index-Reader-Extensions"></a>

<p>SBCL supports extended package prefix syntax, which allows specifying
an alternate package instead of <code>*package*</code> for the reader to use
as the default package for interning symbols:
</p>
<div class="lisp">
<pre class="lisp"><var>package-name</var>::<var>form-with-interning-into-package</var>
</pre></div>

<p>Example:
</p>
<div class="lisp">
<pre class="lisp">  'foo::(bar quux zot) == '(foo::bar foo::quux foo::zot)
</pre></div>

<p>Doesn&rsquo;t alter <code>*package*</code>: if <code>foo::bar</code> would cause a
read-time package lock violation, so does <code>foo::(bar)</code>.
</p>
<p>SBCL also extends the reader to normalize all symbols to Normalization
Form KC in builds with Unicode enabled. Whether symbols are normalized
is controlled by
</p>
<a name="Function-sb_002dext_003areadtable_002dnormalization"></a><dl>
<dt><a name="index-readtable_002dnormalization"></a>Function: <strong>readtable-normalization</strong> <em>[sb-ext] readtable</em></dt>
<dd><p>Returns <code>t</code> if <code>readtable</code> normalizes strings to <code>nfkc</code>, and <code>nil</code> otherwise.
The <code>readtable-normalization</code> of the standard readtable is <code>t</code>.
</p></dd></dl>

<p>Symbols created by
<a name="index-intern-_005bcl_005d"></a>
<code>intern</code> and similar functions are not affected by this setting. If
<code>sb-ext:readtable-normalization</code> is <code>t</code>, symbols that are not
normalized are escaped during printing.
</p>
<hr>
<a name="Package_002dLocal-Nicknames"></a>
<div class="header">
<p>
Next: <a href="#Package-Variance" accesskey="n" rel="next">Package Variance</a>, Previous: <a href="#Reader-Extensions" accesskey="p" rel="prev">Reader Extensions</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package_002dLocal-Nicknames-1"></a>
<h3 class="section">7.2 Package-Local Nicknames</h3>
<a name="index-Package_002dLocal-Nicknames"></a>

<p>SBCL allows giving packages local nicknames: they allow short and
easy-to-use names to be used without fear of name conflict associated
with normal nicknames.
</p>
<p>A local nickname is valid only when inside the package for which it
has been specified. Different packages can use same local nickname for
different global names, or different local nickname for same global
name.
</p>
<p>Symbol <code>:package-local-nicknames</code> in <code>*features*</code> denotes the
support for this feature.
</p>
<a name="index-defpackage-_005bcl_005d"></a>
<dl>
<dt><a name="index-defpackage"></a>Macro: <strong>defpackage</strong> <em>[cl] name [[option]]* &rArr; package</em></dt>
<dd>
<p>Options are extended to include
</p>
<ul>
<li> <code>:local-nicknames (<var>local-nickname</var> <var>actual-package-name</var>)*</code>

<p>The package has the specified local nicknames for the corresponding
actual packages.
</p></li></ul>

<p>Example:
</p>
<div class="lisp">
<pre class="lisp">(defpackage :bar (:intern &quot;X&quot;))
(defpackage :foo (:intern &quot;X&quot;))
(defpackage :quux (:use :cl) (:local-nicknames (:bar :foo) (:foo :bar)))
(find-symbol &quot;X&quot; :foo) ; =&gt; FOO::X
(find-symbol &quot;X&quot; :bar) ; =&gt; BAR::X
(let ((*package* (find-package :quux)))
  (find-symbol &quot;X&quot; :foo))               ; =&gt; BAR::X
(let ((*package* (find-package :quux)))
  (find-symbol &quot;X&quot; :bar))               ; =&gt; FOO::X
</pre></div>
</dd></dl>

<a name="Function-sb_002dext_003apackage_002dlocal_002dnicknames"></a><dl>
<dt><a name="index-package_002dlocal_002dnicknames"></a>Function: <strong>package-local-nicknames</strong> <em>[sb-ext] package-designator</em></dt>
<dd><p>Returns an alist of (local-nickname . actual-package) describing the
nicknames local to the designated package.
</p>
<p>When in the designated package, calls to <code>find-package</code> with the any of the
local-nicknames will return the corresponding actual-package instead. This
also affects all implied calls to <code>find-package</code>, including those performed by
the reader.
</p>
<p>When printing a package prefix for a symbol with a package local nickname, the
local nickname is used instead of the real name in order to preserve
print-read consistency.
</p>
<p>See also: <code>add-package-local-nickname</code>, <code>package-locally-nicknamed-by-list</code>,
<code>remove-package-local-nickname</code>, and the <code>defpackage</code> option <code>:local-nicknames</code>.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003apackage_002dlocally_002dnicknamed_002dby_002dlist"></a><dl>
<dt><a name="index-package_002dlocally_002dnicknamed_002dby_002dlist"></a>Function: <strong>package-locally-nicknamed-by-list</strong> <em>[sb-ext] package-designator</em></dt>
<dd><p>Returns a list of packages which have a local nickname for the designated
package.
</p>
<p>See also: <code>add-package-local-nickname</code>, <code>package-local-nicknames</code>,
<code>remove-package-local-nickname</code>, and the <code>defpackage</code> option <code>:local-nicknames</code>.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003aadd_002dpackage_002dlocal_002dnickname"></a><dl>
<dt><a name="index-add_002dpackage_002dlocal_002dnickname"></a>Function: <strong>add-package-local-nickname</strong> <em>[sb-ext] local-nickname actual-package &amp;optional package-designator</em></dt>
<dd><p>Adds <code>local-nickname</code> for <code>actual-package</code> in the designated package, defaulting
to current package. <code>local-nickname</code> must be a string designator, and
<code>actual-package</code> must be a package designator.
</p>
<p>Returns the designated package.
</p>
<p>Signals a continuable error if <code>local-nickname</code> is already a package local
nickname for a different package, or if <code>local-nickname</code> is one of &quot;CL&quot;,
&quot;COMMON-LISP&quot;, or, &quot;KEYWORD&quot;, or if <code>local-nickname</code> is a global name or
nickname for the package to which the nickname would be added.
</p>
<p>When in the designated package, calls to <code>find-package</code> with the <code>local-nickname</code>
will return the package the designated <code>actual-package</code> instead. This also
affects all implied calls to <code>find-package</code>, including those performed by the
reader.
</p>
<p>When printing a package prefix for a symbol with a package local nickname,
local nickname is used instead of the real name in order to preserve
print-read consistency.
</p>
<p>See also: <code>package-local-nicknames</code>, <code>package-locally-nicknamed-by-list</code>,
<code>remove-package-local-nickname</code>, and the <code>defpackage</code> option <code>:local-nicknames</code>.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003aremove_002dpackage_002dlocal_002dnickname"></a><dl>
<dt><a name="index-remove_002dpackage_002dlocal_002dnickname"></a>Function: <strong>remove-package-local-nickname</strong> <em>[sb-ext] old-nickname &amp;optional package-designator</em></dt>
<dd><p>If the designated package had <code>old-nickname</code> as a local nickname for
another package, it is removed. Returns true if the nickname existed and was
removed, and <code>nil</code> otherwise.
</p>
<p>See also: <code>add-package-local-nickname</code>, <code>package-local-nicknames</code>,
<code>package-locally-nicknamed-by-list</code>, and the <code>defpackage</code> option <code>:local-nicknames</code>.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>

<hr>
<a name="Package-Variance"></a>
<div class="header">
<p>
Next: <a href="#Garbage-Collection" accesskey="n" rel="next">Garbage Collection</a>, Previous: <a href="#Package_002dLocal-Nicknames" accesskey="p" rel="prev">Package-Local Nicknames</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Variance-1"></a>
<h3 class="section">7.3 Package Variance</h3>

<p>Common Lisp standard specifies that &ldquo;If the new definition is at
variance with the current state of that package, the consequences are
undefined;&rdquo; SBCL by default signals a full warning and retains as
much of the package state as possible.
</p>
<p>This can be adjusted using <code>sb-ext:*on-package-variance*</code>:
</p>
<a name="Variable-sb_002dext_003a_002aon_002dpackage_002dvariance_002a"></a><dl>
<dt><a name="index-_002aon_002dpackage_002dvariance_002a"></a>Variable: <strong>*on-package-variance*</strong> <em>[sb-ext]</em></dt>
<dd><p>Specifies behavior when redefining a package using <code>defpackage</code> and the
definition is in variance with the current state of the package.
</p>
<p>The value should be of the form:
</p>
<div class="lisp">
<pre class="lisp">  (:WARN [T | packages-names] :ERROR [T | package-names])
</pre></div>

<p>specifying which packages get which behaviour <code>--</code> with <code>t</code> signifying the default unless
otherwise specified. If default is not specified, <code>:warn</code> is used.
</p>
<p><code>:warn</code> keeps as much state as possible and causes <code>sbcl</code> to signal a full warning.
</p>
<p><code>:error</code> causes <code>sbcl</code> to signal an error when the variant <code>defpackage</code> form is executed,
with restarts provided for user to specify what action should be taken.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">  (setf *on-package-variance* '(:warn (:swank :swank-backend) :error t))
</pre></div>

<p>specifies to signal a warning if <code>swank</code> package is in variance, and an error otherwise.
</p></dd></dl>

<hr>
<a name="Garbage-Collection"></a>
<div class="header">
<p>
Next: <a href="#Metaobject-Protocol" accesskey="n" rel="next">Metaobject Protocol</a>, Previous: <a href="#Package-Variance" accesskey="p" rel="prev">Package Variance</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Garbage-Collection-1"></a>
<h3 class="section">7.4 Garbage Collection</h3>
<a name="index-Garbage-collection"></a>

<p>SBCL provides additional garbage collection functionality not
specified by ANSI.
</p>
<a name="Variable-sb_002dext_003a_002aafter_002dgc_002dhooks_002a"></a><dl>
<dt><a name="index-_002aafter_002dgc_002dhooks_002a"></a>Variable: <strong>*after-gc-hooks*</strong> <em>[sb-ext]</em></dt>
<dd><p>Called after each garbage collection, except for garbage collections
triggered during thread exits. In a multithreaded environment these hooks may
run in any thread.
</p></dd></dl>
<a name="Function-sb_002dext_003agc"></a><dl>
<dt><a name="index-gc"></a>Function: <strong>gc</strong> <em>[sb-ext] &amp;key full gen &amp;allow-other-keys</em></dt>
<dd><p>Initiate a garbage collection.
</p>
<p>The default is to initiate a nursery collection, which may in turn
trigger a collection of one or more older generations as well. If <code>full</code>
is true, all generations are collected. If <code>gen</code> is provided, it can be
used to specify the oldest generation guaranteed to be collected.
</p>
<p>On CheneyGC platforms arguments <code>full</code> and <code>gen</code> take no effect: a full
collection is always performed.
</p></dd></dl>

<a name="Finalization"></a>
<h4 class="subsection">7.4.1 Finalization</h4>
<a name="index-Finalization"></a>

<p>Finalization allows code to be executed after an object has been
garbage collected. This is useful for example for releasing foreign
memory associated with a Lisp object.
</p>
<a name="Function-sb_002dext_003afinalize"></a><dl>
<dt><a name="index-finalize"></a>Function: <strong>finalize</strong> <em>[sb-ext] object function &amp;key dont-save</em></dt>
<dd><p>Arrange for the designated <code>function</code> to be called when there
are no more references to <code>object</code>, including references in
<code>function</code> itself.
</p>
<p>If <code>dont-save</code> is true, the finalizer will be cancelled when
<code>save-lisp-and-die</code> is called: this is useful for finalizers
deallocating system memory, which might otherwise be called
with addresses from the old image.
</p>
<p>In a multithreaded environment <code>function</code> may be called in any
thread. In both single and multithreaded environments <code>function</code>
may be called in any dynamic scope: consequences are unspecified
if <code>function</code> is not fully re-entrant.
</p>
<p>Errors from <code>function</code> are handled and cause a <code>warning</code> to be
signalled in whichever thread the <code>function</code> was called in.
</p>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">  ;;; GOOD, assuming 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 &quot;recursive OOPS&quot;))
   (let ((*rec* t))
     (gc))) ; or just cons enough to cause one

  (progn
    (finalize &quot;oops&quot; #'oops)
    (oops)) ; GC causes re-entry to #'oops due to the finalizer
            ; -&gt; ERROR, caught, WARNING signalled
</pre></div>
</dd></dl>
<a name="Function-sb_002dext_003acancel_002dfinalization"></a><dl>
<dt><a name="index-cancel_002dfinalization"></a>Function: <strong>cancel-finalization</strong> <em>[sb-ext] object</em></dt>
<dd><p>Cancel any finalization for <code>object</code>.
</p></dd></dl>

<a name="Weak-Pointers"></a>
<h4 class="subsection">7.4.2 Weak Pointers</h4>
<a name="index-Weak-pointers"></a>

<p>Weak pointers allow references to objects to be maintained without
keeping them from being garbage collected: useful for building caches
among other things.
</p>
<p>Hash tables can also have weak keys and values: see <a href="#Hash-Table-Extensions">Hash Table Extensions</a>.
</p>
<a name="Function-sb_002dext_003amake_002dweak_002dpointer"></a><dl>
<dt><a name="index-make_002dweak_002dpointer"></a>Function: <strong>make-weak-pointer</strong> <em>[sb-ext] object</em></dt>
<dd><p>Allocate and return a weak pointer which points to <code>object</code>.
</p></dd></dl>
<a name="Function-sb_002dext_003aweak_002dpointer_002dvalue"></a><dl>
<dt><a name="index-weak_002dpointer_002dvalue"></a>Function: <strong>weak-pointer-value</strong> <em>[sb-ext] weak-pointer</em></dt>
<dd><p>If <code>weak-pointer</code> is valid, return the value of <code>weak-pointer</code> and <code>t</code>.
If the referent of <code>weak-pointer</code> has been garbage collected,
returns the values <code>nil</code> and <code>nil</code>.
</p></dd></dl>

<a name="Introspection-and-Tuning"></a>
<h4 class="subsection">7.4.3 Introspection and Tuning</h4>

<a name="Variable-sb_002dext_003a_002agc_002drun_002dtime_002a"></a><dl>
<dt><a name="index-_002agc_002drun_002dtime_002a"></a>Variable: <strong>*gc-run-time*</strong> <em>[sb-ext]</em></dt>
<dd><p>Total <code>cpu</code> time spent doing garbage collection (as reported by
<code>get-internal-run-time</code>.) Initialized to zero on startup. It is safe to bind
this to zero in order to measure <code>gc</code> time inside a certain section of code, but
doing so may interfere with results reported by eg. <code>time</code>.
</p></dd></dl>
<a name="Function-sb_002dext_003abytes_002dconsed_002dbetween_002dgcs"></a><dl>
<dt><a name="index-bytes_002dconsed_002dbetween_002dgcs"></a>Function: <strong>bytes-consed-between-gcs</strong> <em>[sb-ext]</em></dt>
<dd><p>The amount of memory that will be allocated before the next garbage
collection is initiated. This can be set with <code>setf</code>.
</p>
<p>On <code>gencgc</code> platforms this is the nursery size, and defaults to 5% of dynamic
space size.
</p>
<p>Note: currently changes to this value are lost when saving core.
</p></dd></dl>
<a name="Function-sb_002dext_003adynamic_002dspace_002dsize"></a><dl>
<dt><a name="index-dynamic_002dspace_002dsize"></a>Function: <strong>dynamic-space-size</strong> <em>[sb-ext]</em></dt>
<dd><p>Size of the dynamic space in bytes.
</p></dd></dl>
<a name="Function-sb_002dext_003aget_002dbytes_002dconsed"></a><dl>
<dt><a name="index-get_002dbytes_002dconsed"></a>Function: <strong>get-bytes-consed</strong> <em>[sb-ext]</em></dt>
<dd><p>Return the number of bytes consed since the program began. Typically
this result will be a consed bignum, so if you have an application (e.g.
profiling) which can&rsquo;t tolerate the overhead of consing bignums, you&rsquo;ll
probably want either to hack in at a lower level (as the code in the
<code>sb-profile</code> package does), or to design a more microefficient interface
and submit it as a patch.
</p></dd></dl>
<a name="Function-sb_002dext_003agc_002dlogfile"></a><dl>
<dt><a name="index-gc_002dlogfile"></a>Function: <strong>gc-logfile</strong> <em>[sb-ext]</em></dt>
<dd><p>Return the pathname used to log garbage collections. Can be <code>setf</code>.
Default is <code>nil</code>, meaning collections are not logged. If non-null, the
designated file is opened before and after each collection, and generation
statistics are appended to it.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002daverage_002dage"></a><dl>
<dt><a name="index-generation_002daverage_002dage"></a>Function: <strong>generation-average-age</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Average age of memory allocated to <code>generation:</code> average number of times
objects allocated to the generation have seen younger objects promoted to it.
Available on <code>gencgc</code> platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002dbytes_002dallocated"></a><dl>
<dt><a name="index-generation_002dbytes_002dallocated"></a>Function: <strong>generation-bytes-allocated</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Number of bytes allocated to <code>generation</code> currently. Available on <code>gencgc</code>
platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002dbytes_002dconsed_002dbetween_002dgcs"></a><dl>
<dt><a name="index-generation_002dbytes_002dconsed_002dbetween_002dgcs"></a>Function: <strong>generation-bytes-consed-between-gcs</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Number of bytes that can be allocated to <code>generation</code> before that
generation is considered for garbage collection. This value is meaningless for
generation 0 (the nursery): see <code>bytes-consed-between-gcs</code> instead. Default is
5% of the dynamic space size divided by the number of non-nursery generations.
Can be assigned to using <code>setf</code>. Available on <code>gencgc</code> platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002dminimum_002dage_002dbefore_002dgc"></a><dl>
<dt><a name="index-generation_002dminimum_002dage_002dbefore_002dgc"></a>Function: <strong>generation-minimum-age-before-gc</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Minimum average age of objects allocated to <code>generation</code> before that
generation is may be garbage collected. Default is 0.75. See also
<code>generation-average-age</code>. Can be assigned to using <code>setf</code>. Available on <code>gencgc</code>
platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002dnumber_002dof_002dgcs_002dbefore_002dpromotion"></a><dl>
<dt><a name="index-generation_002dnumber_002dof_002dgcs_002dbefore_002dpromotion"></a>Function: <strong>generation-number-of-gcs-before-promotion</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Number of times garbage collection is done on <code>generation</code> before
automatic promotion to the next generation is triggered. Default is 1. Can be
assigned to using <code>setf</code>. Available on <code>gencgc</code> platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003ageneration_002dnumber_002dof_002dgcs"></a><dl>
<dt><a name="index-generation_002dnumber_002dof_002dgcs"></a>Function: <strong>generation-number-of-gcs</strong> <em>[sb-ext] generation</em></dt>
<dd><p>Number of times garbage collection has been done on <code>generation</code> without
promotion. Available on <code>gencgc</code> platforms only.
</p>
<p>Experimental: interface subject to change.
</p></dd></dl>

<hr>
<a name="Metaobject-Protocol"></a>
<div class="header">
<p>
Next: <a href="#Extensible-Sequences" accesskey="n" rel="next">Extensible Sequences</a>, Previous: <a href="#Garbage-Collection" accesskey="p" rel="prev">Garbage Collection</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Metaobject-Protocol-1"></a>
<h3 class="section">7.5 Metaobject Protocol</h3>

<a name="AMOP-Compatibility-of-Metaobject-Protocol"></a>
<h4 class="subsection">7.5.1 AMOP Compatibility of Metaobject Protocol</h4>

<p>SBCL supports a metaobject protocol which is intended to be compatible
with AMOP; present exceptions to this (as distinct from current bugs)
are:
</p>
<ul>
<li> <a name="index-compute_002deffective_002dmethod-_005bsb_002dmop_005d"></a>
<code>compute-effective-method</code> only returns one value, not two.

<p>There is no record of what the second return value was meant to
indicate, and apparently no clients for it.
</p>
</li><li> <a name="index-generic_002dfunction-_005bcl_005d"></a>
<a name="index-standard_002dgeneric_002dfunction-_005bcl_005d"></a>
<a name="index-funcallable_002dstandard_002dobject-_005bsb_002dmop_005d"></a>
<a name="index-standard_002dobject-_005bcl_005d"></a>
<a name="index-function-_005bcl_005d"></a>
The direct superclasses of <code>funcallable-standard-object</code> are
<code>(function standard-object)</code>, not <code>(standard-object function)</code>.

<p>This is to ensure that the <code>standard-object</code> class is the last of
the standardized classes before <code>t</code> appearing in the class
precedence list of <code>generic-function</code> and
<code>standard-generic-function</code>, as required by section 1.4.4.5 of the
ANSI specification.
</p>
</li><li> <a name="index-ensure_002dgeneric_002dfunction-_005bcl_005d"></a>
<a name="index-generic_002dfunction_002ddeclarations-_005bsb_002dmop_005d"></a>
the arguments <code>:declare</code> and <code>:declarations</code> to
<code>ensure-generic-function</code> are both accepted, with the leftmost
argument defining the declarations to be stored and returned by
<code>generic-function-declarations</code>.

<p>Where AMOP specifies <code>:declarations</code> as the keyword argument to
<code>ensure-generic-function</code>, the Common Lisp standard specifies
<code>:declare</code>.  Portable code should use <code>:declare</code>.
</p>
</li><li> <a name="index-validate_002dsuperclass-_005bsb_002dmop_005d"></a>
<a name="index-finalize_002dinheritance-_005bsb_002dmop_005d"></a>
<a name="index-standard_002dclass-_005bcl_005d"></a>
<a name="index-funcallable_002dstandard_002dclass-_005bsb_002dmop_005d"></a>
<a name="index-function-_005bcl_005d-1"></a>
<a name="index-class_002dprototype-_005bsb_002dmop_005d"></a>
although SBCL obeys the requirement in AMOP that
<code>validate-superclass</code> should treat <code>standard-class</code> and
<code>funcallable-standard-class</code> as compatible metaclasses, we
impose an additional requirement at class finalization time: a class
of metaclass <code>funcallable-standard-class</code> must have
<code>function</code> in its superclasses, and a class of metaclass
<code>standard-class</code> must not.

<a name="index-typep-_005bcl_005d"></a>
<a name="index-class_002dof-_005bcl_005d"></a>
<a name="index-subtypep-_005bcl_005d"></a>
<p>After a class has been finalized, it is associated with a class
prototype which is accessible by a standard mop function
<code>class-prototype</code>.  The user can then ask whether this object is a
<code>function</code> or not in several different ways: whether it is a
function according to <code>typep</code>; whether its <code>class-of</code> is
<code>subtypep</code> <code>function</code>, or whether <code>function</code> appears in
the superclasses of the class.  The additional consistency requirement
comes from the desire to make all of these answers the same.
</p>
<p>The following class definitions are bad, and will lead to errors
either immediately or if an instance is created:
</p><div class="lisp">
<pre class="lisp">(defclass bad-object (funcallable-standard-object)
  ()
  (:metaclass standard-class))
</pre></div>
<div class="lisp">
<pre class="lisp">(defclass bad-funcallable-object (standard-object)
  ()
  (:metaclass funcallable-standard-class))
</pre></div>
<p>The following definition is acceptable:
</p><div class="lisp">
<pre class="lisp">(defclass mixin ()
  ((slot :initarg slot)))
(defclass funcallable-object (funcallable-standard-object mixin)
  ()
  (:metaclass funcallable-standard-class))
</pre></div>
<p>and leads to a class whose instances are funcallable and have one slot.
</p>
<a name="index-funcallable_002dstandard_002dobject-_005bsb_002dmop_005d-1"></a>
<p>Note that this requirement also applies to the class
<code>funcallable-standard-object</code>, which has metaclass
<code>funcallable-standard-class</code> rather than
<code>standard-class</code> as AMOP specifies.
</p>
</li><li> the requirement that &ldquo;No portable class <em>C_p</em> 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
<code>common-lisp-user</code> package or exported by any package defined in
the ANSI Common Lisp standard.&rdquo; is interpreted to mean that the
standardized classes themselves should not have slots named by external
symbols of public packages.

<p>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.
</p>
</li><li> <a name="index-slot_002dvalue_002dusing_002dclass-_005bsb_002dmop_005d"></a>
<a name="index-_0028setf-slot_002dvalue_002dusing_002dclass-_005bsb_002dmop_005d_0029"></a>
<a name="index-slot_002dboundp_002dusing_002dclass-_005bsb_002dmop_005d"></a>
specializations of the <code>new-value</code> argument to <code>(setf
slot-value-using-class)</code> are not allowed: all user-defined methods must
have a specializer of the class <code>t</code>.

<p>This prohibition is motivated by a separation of layers: the
<code>slot-value-using-class</code> 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 <code>(setf
slot-value-using-class)</code>, which permits optimization of <code>(setf
slot-value-using-class)</code>&rsquo;s discriminating function in the same manner as
for <code>slot-value-using-class</code> and <code>slot-boundp-using-class</code>.
</p>
<p>Note that application code may specialize on the <code>new-value</code>
argument of slot accessors.
</p>
</li><li> <a name="index-defclass-_005bcl_005d"></a>
<a name="index-ensure_002dclass-_005bsb_002dmop_005d"></a>
<a name="index-ensure_002dclass_002dusing_002dclass-_005bsb_002dmop_005d"></a>
<a name="index-find_002dclass-_005bcl_005d"></a>
<a name="index-class_002dname-_005bcl_005d"></a>
the class named by the <code>name</code> argument to <code>ensure-class</code>, if
any, is only redefined if it is the proper name of that class;
otherwise, a new class is created.

<p>This is consistent with the description of <code>ensure-class</code> in AMOP
as the functional version of <code>defclass</code>, which has this behaviour;
however, it is not consistent with the weaker requirement in AMOP, which
states that any class found by <code>find-class</code>, no matter what its
<code>class-name</code>, is redefined.
</p>
</li><li> <a name="index-slot_002ddefinition_002dname-_005bsb_002dmop_005d"></a>
<a name="index-structure_002dclass-_005bcl_005d"></a>
<a name="index-defstruct-_005bcl_005d"></a>
an error is not signaled in the case of the <code>:name</code> initialization
argument for <code>slot-definition</code> objects being a constant, when the
slot definition is of type <code>structure-slot-definition</code> (i.e. it is
associated with a class of type <code>structure-class</code>).

<p>This allows code which uses constant names for structure slots to
continue working as specified in ANSI, while enforcing the constraint
for all other types of slot.
</p>
</li><li> <a name="index-t-_005bcl_005d"></a>
<a name="index-built_002din_002dclass-_005bcl_005d"></a>
<a name="index-validate_002dsuperclass-_005bsb_002dmop_005d-1"></a>
<a name="index-defclass-_005bcl_005d-1"></a>
the class named <code>t</code> is not an instance of the <code>built-in-class</code>
metaclass.

<p>AMOP specifies, in the &ldquo;Inheritance Structure of Metaobject Classes&rdquo;
section, that the class named <code>t</code> should be an instance of
<code>built-in-class</code>.  However, it also specifies that
<code>validate-superclass</code> should return true (indicating that a direct
superclass relationship is permissible) if the second argument is the
class named <code>t</code>.  Also, ANSI specifies that classes with metaclass
<code>built-in-class</code> may not be subclassed using <code>defclass</code>, and
also that the class named <code>t</code> is the universal superclass,
inconsistent with it being a <code>built-in-class</code>.
</p>
</li></ul>

<a name="Metaobject-Protocol-Extensions"></a>
<h4 class="subsection">7.5.2 Metaobject Protocol Extensions</h4>

<p>In addition, SBCL supports extensions to the Metaobject protocol from
AMOP; at present, they are:
</p>
<ul>
<li> <a name="index-defmethod-_005bcl_005d"></a>
<a name="index-find_002dclass-_005bcl_005d-1"></a>
<a name="index-intern_002deql_002dspecializer-_005bsb_002dmop_005d"></a>
<a name="index-make_002dmethod_002dspecializers_002dform-_005bsb_002dpcl_005d"></a>
<a name="index-make_002dmethod_002dlambda-_005bsb_002dmop_005d"></a>
compile-time support for generating specializer metaobjects from
specializer names in <code>defmethod</code> forms is provided by the
<code>make-method-specializers-form</code> function, which returns a form
which, when evaluated in the lexical environment of the
<code>defmethod</code>, returns a list of specializer metaobjects.  This
operator suffers from similar restrictions to those affecting
<code>make-method-lambda</code>, namely that the generic function must be
defined when the <code>defmethod</code> form is expanded, so that the
correct method of <code>make-method-specializers-form</code> is invoked.
The system-provided method on <code>make-method-specializers-form</code>
generates a call to <code>find-class</code> for each symbol specializer
name, and a call to <code>intern-eql-specializer</code> for each <code>(eql
<var>x</var>)</code> specializer name.

</li><li> <a name="index-find_002dmethod-_005bcl_005d"></a>
<a name="index-parse_002dspecializer_002dusing_002dclass-_005bsb_002dpcl_005d"></a>
<a name="index-unparse_002dspecializer_002dusing_002dclass-_005bsb_002dpcl_005d"></a>
run-time support for converting between specializer names and
specializer metaobjects, mostly for the purposes of
<code>find-method</code>, is provided by
<code>parse-specializer-using-class</code> and
<code>unparse-specializer-using-class</code>, 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
<code>(eql <var>x</var>)</code> and interned eql specializer objects.

</li><li> <a name="index-_002bslot_002dunbound_002b-_005bsb_002dpcl_005d"></a>
<a name="index-standard_002dinstance_002daccess-_005bsb_002dmop_005d"></a>
<a name="index-funcallable_002dstandard_002dinstance_002daccess-_005bsb_002dmop_005d"></a>
distinguishing unbound instance allocated slots from bound ones when
using <code>standard-instance-access</code> and
<code>funcallable-standard-instance-access</code> is possible by comparison
to the constant <code>+slot-unbound+</code>.

</li></ul>

<hr>
<a name="Extensible-Sequences"></a>
<div class="header">
<p>
Next: <a href="#Support-For-Unix" accesskey="n" rel="next">Support For Unix</a>, Previous: <a href="#Metaobject-Protocol" accesskey="p" rel="prev">Metaobject Protocol</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Extensible-Sequences-1"></a>
<h3 class="section">7.6 Extensible Sequences</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Iterator-Protocol" accesskey="1">Iterator Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Simple-Iterator-Protocol" accesskey="2">Simple Iterator Protocol</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<p>ANSI Common Lisp has a class <code>sequence</code> with subclasses <code>list</code> and
<code>vector</code> on which the &ldquo;sequence functions&rdquo; like <code>find</code>,
<code>subseq</code>, etc. operate. As an extension to the ANSI specification,
SBCL allows additional subclasses of <code>sequence</code> to be defined
<a name="DOCF6" href="#FOOT6"><sup>6</sup></a>.
<a name="index-sequence-_005bcl_005d"></a>
<a name="index-vector-_005bcl_005d-1"></a>
<a name="index-find-_005bcl_005d"></a>
<a name="index-subseq-_005bcl_005d"></a>
</p>
<p>Users of this extension just make instances of <code>sequence</code> subclasses
and transparently operate on them using sequence functions:
</p><div class="lisp">
<pre class="lisp">(coerce (subseq (make-instance 'my-sequence) 5 10) 'list)
</pre></div>
<p>From this perspective, no distinction between builtin and user-defined
<code>sequence</code> subclasses should be necessary.
<a name="index-coerce-_005bcl_005d"></a>
<a name="index-subseq-_005bcl_005d-1"></a>
<a name="index-make_002dinstance-_005bcl_005d"></a>
<a name="index-list-_005bcl_005d-1"></a>
</p>
<p>Providers of the extension, that is of user-defined <code>sequence</code>
subclasses, have to adhere to a &ldquo;sequence protocol&rdquo; which consists of
a set of generic functions in the <code>sequence</code> package.
</p>
<p>A minimal <code>sequence</code> subclass has to specify <code>standard-object</code> and
<code>sequence</code> as its superclasses and has to be the specializer of the
<code>sequence</code> parameter of methods on at least the following generic
functions:
<a name="index-sequence-_005bcl_005d-1"></a>
<a name="index-standard_002dobject-_005bcl_005d-1"></a>
</p>
<a name="Generic_002dFunction-sb_002dsequence_003alength"></a><dl>
<dt><a name="index-length"></a>Generic Function: <strong>length</strong> <em>[sb-sequence] sequence</em></dt>
<dd><p>Returns the length of <code>sequence</code> or signals a <code>protocol-unimplemented</code>
   error if the sequence protocol is not implemented for the class of
   <code>sequence</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aelt"></a><dl>
<dt><a name="index-elt"></a>Generic Function: <strong>elt</strong> <em>[sb-sequence] sequence index</em></dt>
<dd><p>Returns the element at position <code>index</code> of <code>sequence</code> or signals a
   <code>protocol-unimplemented</code> error if the sequence protocol is not
   implemented for the class of <code>sequence</code>.
</p></dd></dl>
<a name="Generic_002dFunction-_0028setf-sb_002dsequence_003aelt_0029"></a><dl>
<dt><a name="index-_0028setf"></a>Generic Function: <strong>(setf</strong> <em>elt [sb-sequence])</em></dt>
<dd><p>Replaces the element at position <code>index</code> of <code>sequence</code> with <code>new-value</code>
   and returns <code>new-value</code> or signals a <code>protocol-unimplemented</code> error if
   the sequence protocol is not implemented for the class of
   <code>sequence</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aadjust_002dsequence"></a><dl>
<dt><a name="index-adjust_002dsequence"></a>Generic Function: <strong>adjust-sequence</strong> <em>[sb-sequence] sequence length &amp;key initial-element initial-contents</em></dt>
<dd><p>Return destructively modified <code>sequence</code> or a freshly allocated
   sequence of the same class as <code>sequence</code> of length <code>length</code>. Elements
   of the returned sequence are initialized to <code>initial-element</code>, if
   supplied, initialized to <code>initial-contents</code> if supplied, or identical
   to the elements of <code>sequence</code> if neither is supplied. Signals a
   <code>protocol-unimplemented</code> error if the sequence protocol is not
   implemented for the class of <code>sequence</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003amake_002dsequence_002dlike"></a><dl>
<dt><a name="index-make_002dsequence_002dlike"></a>Generic Function: <strong>make-sequence-like</strong> <em>[sb-sequence] sequence length &amp;key initial-element initial-contents</em></dt>
<dd><p>Returns a freshly allocated sequence of length <code>length</code> and of the
   same class as <code>sequence</code>. Elements of the new sequence are
   initialized to <code>initial-element</code>, if supplied, initialized to
   <code>initial-contents</code> if supplied, or identical to the elements of
   <code>sequence</code> if neither is supplied. Signals a <code>protocol-unimplemented</code>
   error if the sequence protocol is not implemented for the class of
   <code>sequence</code>.
</p></dd></dl>

<p><code>make-sequence-like</code> is needed for functions returning
freshly-allocated sequences such as <code>subseq</code> or
<code>copy-seq</code>. <code>adjust-sequence</code> is needed for functions which
destructively modify their arguments such as <code>delete</code>. In fact, all
other sequence functions can be implemented in terms of the above
functions and actually are, if no additional methods are
defined. However, relying on these generic implementations, in
particular not implementing the iterator protocol can incur a high
performance penalty See <a href="#Iterator-Protocol">Iterator Protocol</a>.
<a name="index-sequence-_005bcl_005d-2"></a>
<a name="index-make_002dsequence_002dlike-_005bsb_002dsequence_005d"></a>
<a name="index-subseq-_005bcl_005d-2"></a>
<a name="index-copy_002dseq-_005bcl_005d"></a>
<a name="index-adjust_002dsequence-_005bsb_002dsequence_005d"></a>
</p>
<p>When the sequence protocol is only partially implemented for a given
<code>sequence</code> subclass, an attempt to apply one of the missing
operations to instances of that class signals the following condition:
</p>
<a name="Condition-sb_002dsequence_003aprotocol_002dunimplemented"></a><dl>
<dt><a name="index-protocol_002dunimplemented"></a>Condition: <strong>protocol-unimplemented</strong> <em>[sb-sequence]</em></dt>
<dd><p>Class precedence list: <code>protocol-unimplemented, type-error, error, serious-condition, condition, t</code>
</p>
<p>This error is signaled if a sequence operation is applied to an
   instance of a sequence class that does not support the
   operation.
</p></dd></dl>

<p>In addition to the mandatory functions above, methods on the sequence
functions listed below can be defined.
</p>
<p>There are two noteworthy irregularities:
</p><ul>
<li> The function <code>sb-sequence:emptyp</code> does not have a counterpart in
the <code>cl</code> package. It is intended to be used instead of
<code>length</code> when working with lazy or infinite sequences.

</li><li> The functions <code>map</code>, <code>concatenate</code> and <code>merge</code> receive a
type designator specifying the type of the constructed sequence as their
first argument. However, the corresponding generic functions
<code>sb-sequence:map</code>, <code>sb-sequence:concatenate</code> and
<code>sb-sequence:merge</code> receive a prototype instance of the requested
<code>sequence</code> subclass instead.
</li></ul>

<a name="Generic_002dFunction-sb_002dsequence_003aemptyp"></a><dl>
<dt><a name="index-emptyp"></a>Generic Function: <strong>emptyp</strong> <em>[sb-sequence] sequence</em></dt>
<dd><p>Returns <code>t</code> if <code>sequence</code> is an empty sequence and <code>nil</code>
   otherwise. Signals an error if <code>sequence</code> is not a sequence.
</p></dd></dl>

<ul>
<li> <code>sb-sequence:count</code>, <code>sb-sequence:count-if</code>, <code>sb-sequence:count-if-not</code>

</li><li> <code>sb-sequence:find</code>, <code>sb-sequence:find-if</code>, <code>sb-sequence:find-if-not</code>

</li><li> <code>sb-sequence:position</code>, <code>sb-sequence:position-if</code>, <code>sb-sequence:position-if-not</code>

</li><li> <code>sb-sequence:subseq</code>

</li><li> <code>sb-sequence:copy-seq</code>

</li><li> <code>sb-sequence:fill</code>

</li><li> <a name="Generic_002dFunction-sb_002dsequence_003amap"></a><dl>
<dt><a name="index-map"></a>Generic Function: <strong>map</strong> <em>[sb-sequence] result-prototype function sequence &amp;rest sequences</em></dt>
<dd><p>Implements <code>cl:map</code> for extended sequences.
</p>
<p><code>result-prototype</code> corresponds to the <code>result-type</code> of <code>cl:map</code> but
    receives a prototype instance of an extended sequence class
    instead of a type specifier. By dispatching on <code>result-prototype</code>,
    methods on this generic function specify how extended sequence
    classes act when they are specified as the result type in a <code>cl:map</code>
    call. <code>result-prototype</code> may not be fully initialized and thus
    should only be used for dispatch and to determine its class.
</p>
<p>Another difference to <code>cl:map</code> is that <code>function</code> is a function, not a
    function designator.
</p></dd></dl>

</li><li> <code>sb-sequence:nsubstitute</code>, <code>sb-sequence:nsubstitute-if</code>,
<code>sb-sequence:nsubstitute-if-not</code>, <code>sb-sequence:substitute</code>,
<code>sb-sequence:substitute-if</code>, <code>sb-sequence:substitute-if-not</code>

</li><li> <code>sb-sequence:replace</code>

</li><li> <code>sb-sequence:nreverse</code>, <code>sb-sequence:reverse</code>

</li><li> <a name="Generic_002dFunction-sb_002dsequence_003aconcatenate"></a><dl>
<dt><a name="index-concatenate"></a>Generic Function: <strong>concatenate</strong> <em>[sb-sequence] result-prototype &amp;rest sequences</em></dt>
<dd><p>Implements <code>cl:concatenate</code> for extended sequences.
</p>
<p><code>result-prototype</code> corresponds to the <code>result-type</code> of <code>cl:concatenate</code>
    but receives a prototype instance of an extended sequence class
    instead of a type specifier. By dispatching on <code>result-prototype</code>,
    methods on this generic function specify how extended sequence
    classes act when they are specified as the result type in a
    <code>cl:concatenate</code> call. <code>result-prototype</code> may not be fully initialized
    and thus should only be used for dispatch and to determine its
    class.
</p></dd></dl>

</li><li> <code>sb-sequence:reduce</code>

</li><li> <code>sb-sequence:mismatch</code>

</li><li> <code>sb-sequence:search</code>

</li><li> <code>sb-sequence:delete</code>, <code>sb-sequence:delete-if</code>, <code>sb-sequence:delete-if-not</code>,
<code>sb-sequence:remove</code>, <code>sb-sequence:remove-if</code>, <code>sb-sequence:remove-if-not</code>,

</li><li> <code>sb-sequence:delete-duplicates</code>, <code>sb-sequence:remove-duplicates</code>

</li><li> <code>sb-sequence:sort</code>, <code>sb-sequence:stable-sort</code>

</li><li> <a name="Generic_002dFunction-sb_002dsequence_003amerge"></a><dl>
<dt><a name="index-merge"></a>Generic Function: <strong>merge</strong> <em>[sb-sequence] result-prototype sequence1 sequence2 predicate &amp;key key</em></dt>
<dd><p>Implements <code>cl:merge</code> for extended sequences.
</p>
<p><code>result-prototype</code> corresponds to the <code>result-type</code> of <code>cl:merge</code> but
    receives a prototype instance of an extended sequence class
    instead of a type specifier. By dispatching on <code>result-prototype</code>,
    methods on this generic function specify how extended sequence
    classes act when they are specified as the result type in a
    <code>cl:merge</code> call. <code>result-prototype</code> may not be fully initialized and
    thus should only be used for dispatch and to determine its class.
</p>
<p>Another difference to <code>cl:merge</code> is that <code>predicate</code> is a function,
    not a function designator.
</p></dd></dl>
</li></ul>

<p>In the spirit of <code>dolist</code>, generic sequences can be traversed using
the macro
<a name="index-dolist-_005bcl_005d"></a>
</p>
<a name="Macro-sb_002dsequence_003adosequence"></a><dl>
<dt><a name="index-dosequence"></a>Macro: <strong>dosequence</strong> <em>[sb-sequence] (element sequence &amp;optional return) &amp;body body</em></dt>
<dd><p>Executes <code>body</code> with <code>element</code> subsequently bound to each element of
  <code>sequence</code>, then returns <code>return</code>.
</p></dd></dl>

<hr>
<a name="Iterator-Protocol"></a>
<div class="header">
<p>
Next: <a href="#Simple-Iterator-Protocol" accesskey="n" rel="next">Simple Iterator Protocol</a>, Up: <a href="#Extensible-Sequences" accesskey="u" rel="up">Extensible Sequences</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Iterator-Protocol-1"></a>
<h4 class="subsection">7.6.1 Iterator Protocol</h4>

<p>The iterator protocol allows subsequently accessing some or all elements
of a sequence in forward or reverse direction. Users first call
<code>make-sequence-iterator</code> to create an iteration state and
receive functions to query and mutate it. These functions allow, among
other things, moving to, retrieving or modifying elements of the
sequence. An iteration state consists of a state object, a limit object,
a from-end indicator and the following six functions to query or mutate
this state:
<a name="index-make_002dsequence_002diterator-_005bsb_002dsequence_005d"></a>
</p><dl>
<dt><a name="index-step-function"></a>Function: <strong><code>step function</code></strong> <em>sequence iterator from-end</em></dt>
<dd><p>Moves the iterator one position forward or backward in the associated
sequence depending on the iteration direction.
</p></dd></dl>
<dl>
<dt><a name="index-endp-function"></a>Function: <strong><code>endp function</code></strong> <em>sequence iterator limit from-end</em></dt>
<dd><p>Returns non-<code>nil</code> when the iterator has reached the end of the
associated sequence with respect to the iteration direction.
</p></dd></dl>
<dl>
<dt><a name="index-element-function"></a>Function: <strong><code>element function</code></strong> <em>sequence iterator</em></dt>
<dd><p>Returns the sequence element associated to the current position of the
iteration.
</p></dd></dl>
<dl>
<dt><a name="index-setf-element-function"></a>Function: <strong><code>setf element function</code></strong> <em>new-value sequence iterator</em></dt>
<dd><p>Destructively modifies the associates sequence by replacing the sequence
element associated to the current iteration position with a new value.
</p></dd></dl>
<dl>
<dt><a name="index-index-function"></a>Function: <strong><code>index function</code></strong> <em>sequence iterator</em></dt>
<dd><p>Returns the position of the iteration in the associated sequence.
</p></dd></dl>
<dl>
<dt><a name="index-copy-function"></a>Function: <strong><code>copy function</code></strong> <em>sequence iterator</em></dt>
<dd><p>Returns a copy of the iteration state which can be mutated independently
of the copied iteration state.
</p></dd></dl>

<p>An iterator is created by calling:
</p>
<a name="Generic_002dFunction-sb_002dsequence_003amake_002dsequence_002diterator"></a><dl>
<dt><a name="index-make_002dsequence_002diterator"></a>Generic Function: <strong>make-sequence-iterator</strong> <em>[sb-sequence] sequence &amp;key from-end start end</em></dt>
<dd><p>Returns a sequence iterator for <code>sequence</code> or, if <code>start</code> and/or <code>end</code>
   are supplied, the subsequence bounded by <code>start</code> and <code>end</code> as nine
   values:
</p>
<p>1. iterator state
   2. limit
   3. from-end
   4. step function
   5. endp function
   6. element function
   7. setf element function
   8. index function
   9. copy state function
</p>
<p>If <code>from-end</code> is <code>nil</code>, the constructed iterator visits the specified
   elements in the order in which they appear in <code>sequence</code>. Otherwise,
   the elements are visited in the opposite order.
</p></dd></dl>

<p>Note that <code>make-sequence-iterator</code> calls
<code>make-simple-sequence-iterator</code> when there is no specialized
method for a particular <code>sequence</code> subclass. See <a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a>.
<a name="index-make_002dsequence_002diterator-_005bsb_002dsequence_005d-1"></a>
<a name="index-make_002dsimple_002dsequence_002diterator-_005bsb_002dsequence_005d"></a>
<a name="index-sequence-_005bcl_005d-3"></a>
</p>
<p>The following convenience macros simplify traversing sequences using
iterators:
</p>
<a name="Macro-sb_002dsequence_003awith_002dsequence_002diterator"></a><dl>
<dt><a name="index-with_002dsequence_002diterator"></a>Macro: <strong>with-sequence-iterator</strong> <em>[sb-sequence] (&amp;rest vars) (sequence &amp;rest args &amp;key from-end start end) &amp;body body</em></dt>
<dd><p>Executes <code>body</code> with the elements of <code>vars</code> bound to the iteration
  state returned by <code>make-sequence-iterator</code> for <code>sequence</code> and
  <code>args</code>. Elements of <code>vars</code> may be <code>nil</code> in which case the corresponding
  value returned by <code>make-sequence-iterator</code> is ignored.
</p></dd></dl>
<a name="Macro-sb_002dsequence_003awith_002dsequence_002diterator_002dfunctions"></a><dl>
<dt><a name="index-with_002dsequence_002diterator_002dfunctions"></a>Macro: <strong>with-sequence-iterator-functions</strong> <em>[sb-sequence] (step endp elt setf index copy) (sequence &amp;rest args &amp;key from-end start end) &amp;body body</em></dt>
<dd><p>Executes <code>body</code> with the names <code>step</code>, <code>endp</code>, <code>elt</code>, <code>setf</code>, <code>index</code> and <code>copy</code>
  bound to local functions which execute the iteration state query and
  mutation functions returned by <code>make-sequence-iterator</code> for <code>sequence</code>
  and <code>args</code>. <code>step</code>, <code>endp</code>, <code>elt</code>, <code>setf</code>, <code>index</code> and <code>copy</code> have dynamic
  extent.
</p></dd></dl>

<hr>
<a name="Simple-Iterator-Protocol"></a>
<div class="header">
<p>
Previous: <a href="#Iterator-Protocol" accesskey="p" rel="prev">Iterator Protocol</a>, Up: <a href="#Extensible-Sequences" accesskey="u" rel="up">Extensible Sequences</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Simple-Iterator-Protocol-1"></a>
<h4 class="subsection">7.6.2 Simple Iterator Protocol</h4>

<p>For cases in which the full flexibility and performance of the general
sequence iterator protocol is not required, there is a simplified
sequence iterator protocol consisting of a few generic functions which
can be specialized for iterator classes:
</p>
<a name="Generic_002dFunction-sb_002dsequence_003aiterator_002dstep"></a><dl>
<dt><a name="index-iterator_002dstep"></a>Generic Function: <strong>iterator-step</strong> <em>[sb-sequence] sequence iterator from-end</em></dt>
<dd><p>Moves <code>iterator</code> one position forward or backward in <code>sequence</code>
   depending on the iteration direction encoded in <code>from-end</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aiterator_002dendp"></a><dl>
<dt><a name="index-iterator_002dendp"></a>Generic Function: <strong>iterator-endp</strong> <em>[sb-sequence] sequence iterator limit from-end</em></dt>
<dd><p>Returns non-NIL when <code>iterator</code> has reached <code>limit</code> (which may
   correspond to the end of SEQUENCE) with respect to the iteration
   direction encoded in <code>from-end</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aiterator_002delement"></a><dl>
<dt><a name="index-iterator_002delement"></a>Generic Function: <strong>iterator-element</strong> <em>[sb-sequence] sequence iterator</em></dt>
<dd><p>Returns the element of <code>sequence</code> associated to the position of
   <code>iterator</code>.
</p></dd></dl>
<a name="Generic_002dFunction-_0028setf-sb_002dsequence_003aiterator_002delement_0029"></a><dl>
<dt><a name="index-_0028setf-1"></a>Generic Function: <strong>(setf</strong> <em>iterator-element [sb-sequence])</em></dt>
<dd><p>Destructively modifies <code>sequence</code> by replacing the sequence element
   associated to position of <code>iterator</code> with <code>new-value</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aiterator_002dindex"></a><dl>
<dt><a name="index-iterator_002dindex"></a>Generic Function: <strong>iterator-index</strong> <em>[sb-sequence] sequence iterator</em></dt>
<dd><p>Returns the position of <code>iterator</code> in <code>sequence</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dsequence_003aiterator_002dcopy"></a><dl>
<dt><a name="index-iterator_002dcopy"></a>Generic Function: <strong>iterator-copy</strong> <em>[sb-sequence] sequence iterator</em></dt>
<dd><p>Returns a copy of <code>iterator</code> which also traverses <code>sequence</code> but can
   be mutated independently of <code>iterator</code>.
</p></dd></dl>

<p>Iterator objects implementing the above simple iteration protocol are
created by calling the following generic function:
</p>
<a name="Generic_002dFunction-sb_002dsequence_003amake_002dsimple_002dsequence_002diterator"></a><dl>
<dt><a name="index-make_002dsimple_002dsequence_002diterator"></a>Generic Function: <strong>make-simple-sequence-iterator</strong> <em>[sb-sequence] sequence &amp;key from-end start end</em></dt>
<dd><p>Returns a sequence iterator for <code>sequence</code>, <code>start</code>, <code>end</code> and <code>from-end</code>
   as three values:
</p>
<p>1. iterator state
   2. limit
   3. from-end
</p>
<p>The returned iterator can be used with the generic iterator
   functions <code>iterator-step</code>, <code>iterator-endp</code>, <code>iterator-element</code>, (SETF
   ITERATOR-ELEMENT), <code>iterator-index</code> and <code>iterator-copy</code>.
</p></dd></dl>

<hr>
<a name="Support-For-Unix"></a>
<div class="header">
<p>
Next: <a href="#Unicode-Support" accesskey="n" rel="next">Unicode Support</a>, Previous: <a href="#Extensible-Sequences" accesskey="p" rel="prev">Extensible Sequences</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Support-For-Unix-1"></a>
<h3 class="section">7.7 Support For Unix</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Command_002dline-arguments" accesskey="1">Command-line arguments</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Querying-the-process-environment" accesskey="2">Querying the process environment</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Running-external-programs" accesskey="3">Running external programs</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Command_002dline-arguments"></a>
<div class="header">
<p>
Next: <a href="#Querying-the-process-environment" accesskey="n" rel="next">Querying the process environment</a>, Up: <a href="#Support-For-Unix" accesskey="u" rel="up">Support For Unix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Command_002dline-arguments-1"></a>
<h4 class="subsection">7.7.1 Command-line arguments</h4>
<a name="index-_002aposix_002dargv_002a-_005bsb_002dext_005d-1"></a>

<p>The UNIX command line can be read from the variable
<code>sb-ext:*posix-argv*</code>.
</p>
<hr>
<a name="Querying-the-process-environment"></a>
<div class="header">
<p>
Next: <a href="#Running-external-programs" accesskey="n" rel="next">Running external programs</a>, Previous: <a href="#Command_002dline-arguments" accesskey="p" rel="prev">Command-line arguments</a>, Up: <a href="#Support-For-Unix" accesskey="u" rel="up">Support For Unix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Querying-the-process-environment-1"></a>
<h4 class="subsection">7.7.2 Querying the process environment</h4>

<p>The UNIX environment can be queried with the
<code>sb-ext:posix-getenv</code> function.
</p>
<a name="Function-sb_002dext_003aposix_002dgetenv"></a><dl>
<dt><a name="index-posix_002dgetenv"></a>Function: <strong>posix-getenv</strong> <em>[sb-ext] name</em></dt>
<dd><p>Return the &quot;value&quot; part of the environment string &quot;name=value&quot; which
corresponds to <code>name</code>, or <code>nil</code> if there is none.
</p></dd></dl>

<hr>
<a name="Running-external-programs"></a>
<div class="header">
<p>
Previous: <a href="#Querying-the-process-environment" accesskey="p" rel="prev">Querying the process environment</a>, Up: <a href="#Support-For-Unix" accesskey="u" rel="up">Support For Unix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Running-external-programs-1"></a>
<h4 class="subsection">7.7.3 Running external programs</h4>

<p>External programs can be run with <code>sb-ext:run-program</code>.
<a name="DOCF7" href="#FOOT7"><sup>7</sup></a>
</p>
<a name="Function-sb_002dext_003arun_002dprogram"></a><dl>
<dt><a name="index-run_002dprogram"></a>Function: <strong>run-program</strong> <em>[sb-ext] program args &amp;key env environment wait search pty input if-input-does-not-exist output if-output-exists error if-error-exists status-hook external-format directory</em></dt>
<dd><p><code>run-program</code> creates a new process specified by the <code>program</code>
argument. <code>args</code> are the standard arguments that can be passed to a
program. For no arguments, use <code>nil</code> (which means that just the
name of the program is passed as arg 0).
</p>
<p>The program arguments and the environment are encoded using the
default external format for streams.
</p>
<p><code>run-program</code> will return a <code>process</code> structure. See the <code>cmu</code> Common Lisp
Users Manual for details about the <code>process</code> structure.
</p>
<p>Notes about Unix environments (as in the <code>:environment</code> and <code>:env</code> args):
</p>
<ul>
<li> The <code>sbcl</code> implementation of <code>run-program</code>, like Perl and many other
     programs, but unlike the original <code>cmu</code> <code>cl</code> implementation, copies
     the Unix environment by default.
</li><li> 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.)

</li></ul>

<dl compact="compact">
<dt><em>The <code>&amp;key</code> arguments have the following meanings:</em></dt>
<dt><em><code>:environment</code></em></dt>
<dd><p>a list of STRINGs describing the new Unix environment
      (as in &quot;man environ&quot;). The default is to copy the environment of
      the current process.
</p>
</dd>
<dt><em><code>:env</code></em></dt>
<dd><p>an alternative lossy representation of the new Unix environment,
      for compatibility with <code>cmu</code> <code>cl</code>
</p>
</dd>
<dt><em><code>:search</code></em></dt>
<dd><p>Look for <code>program</code> in each of the directories in the child&rsquo;s $PATH
      environment variable.  Otherwise an absolute pathname is required.
</p>
</dd>
<dt><em><code>:wait</code></em></dt>
<dd><p>If non-NIL (default), wait until the created process finishes.  If
      <code>nil</code>, continue running Lisp until the program finishes.
</p>
</dd>
<dt><em><code>:pty</code></em></dt>
<dd><p>Either <code>t</code>, <code>nil</code>, or a stream.  Unless <code>nil</code>, the subprocess is established
      under a <code>pty</code>.  If :pty is a stream, all output to this pty is sent to
      this stream, otherwise the <code>process-pty</code> slot is filled in with a stream
      connected to pty that can read output and write input.
</p>
</dd>
<dt><em><code>:input</code></em></dt>
<dd><p>Either <code>t</code>, <code>nil</code>, a pathname, a stream, or <code>:stream</code>.  If <code>t</code>, the standard
      input for the current process is inherited.  If <code>nil</code>, /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
      <code>:stream</code>, the <code>process-input</code> slot is filled in with a stream that sends
      its output to the process. Defaults to <code>nil</code>.
</p>
</dd>
<dt><em><code>:if-input-does-not-exist</code> (when <code>:input</code> is the name of a file)</em></dt>
<dd><p>can be one of:
         <code>:error</code> to generate an error
         <code>:create</code> to create an empty file
         <code>nil</code> (the default) to return <code>nil</code> from <code>run-program</code>
</p>
</dd>
<dt><em><code>:output</code></em></dt>
<dd><p>Either <code>t</code>, <code>nil</code>, a pathname, a stream, or <code>:stream</code>.  If <code>t</code>, the standard
      output for the current process is inherited.  If <code>nil</code>, /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
      <code>:stream</code>, the <code>process-output</code> slot is filled in with a stream that can
      be read to get the output. Defaults to <code>nil</code>.
</p>
</dd>
<dt><em><code>:if-output-exists</code> (when <code>:output</code> is the name of a file)</em></dt>
<dd><p>can be one of:
         <code>:error</code> (the default) to generate an error
         <code>:supersede</code> to supersede the file with output from the program
         <code>:append</code> to append output from the program to the file
         <code>nil</code> to return <code>nil</code> from <code>run-program</code>, without doing anything
</p>
</dd>
<dt><em><code>:error</code> and <code>:if-error-exists</code></em></dt>
<dd><p>Same as <code>:output</code> and <code>:if-output-exists</code>, except that <code>:error</code> can also be
      specified as <code>:output</code> in which case all error output is routed to the
      same place as normal output.
</p>
</dd>
<dt><em><code>:status-hook</code></em></dt>
<dd><p>This is a function the system calls whenever the status of the
      process changes.  The function takes the process as an argument.
</p>
</dd>
<dt><em><code>:external-format</code></em></dt>
<dd><p>The external-format to use for <code>:input</code>, <code>:output</code>, and <code>:error</code> :STREAMs.
</p>
</dd>
<dt><em><code>:directory</code></em></dt>
<dd><p>Specifies the directory in which the program should be run.
      <code>nil</code> (the default) means the directory is unchanged.
</p>

</dd>
<dt><em>Windows specific options:</em></dt>
<dt><em><code>:escape-arguments</code> (default T)</em></dt>
<dd><p>Controls escaping of the arguments passed to CreateProcess.
</p></dd>
</dl>

</dd></dl>

<p>When <code>sb-ext:run-program</code> is called with <code>wait</code> equal to
NIL, an instance of class <var>sb-ext:process</var> is returned.  The
following functions are available for use with processes:
</p>
<a name="Function-sb_002dext_003aprocess_002dp"></a><dl>
<dt><a name="index-process_002dp"></a>Function: <strong>process-p</strong> <em>[sb-ext] object</em></dt>
<dd><p><code>t</code> if <code>object</code> is a <code>process</code>, <code>nil</code> otherwise.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dinput"></a><dl>
<dt><a name="index-process_002dinput"></a>Function: <strong>process-input</strong> <em>[sb-ext] instance</em></dt>
<dd><p>The input stream of the process or <code>nil</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002doutput"></a><dl>
<dt><a name="index-process_002doutput"></a>Function: <strong>process-output</strong> <em>[sb-ext] instance</em></dt>
<dd><p>The output stream of the process or <code>nil</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002derror"></a><dl>
<dt><a name="index-process_002derror"></a>Function: <strong>process-error</strong> <em>[sb-ext] instance</em></dt>
<dd><p>The error stream of the process or <code>nil</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dalive_002dp"></a><dl>
<dt><a name="index-process_002dalive_002dp"></a>Function: <strong>process-alive-p</strong> <em>[sb-ext] process</em></dt>
<dd><p>Return <code>t</code> if <code>process</code> is still alive, <code>nil</code> otherwise.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dstatus"></a><dl>
<dt><a name="index-process_002dstatus"></a>Function: <strong>process-status</strong> <em>[sb-ext] process</em></dt>
<dd><p>Return the current status of <code>process</code>.  The result is one of <code>:running</code>,
   <code>:stopped</code>, <code>:exited</code>, or <code>:signaled</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dwait"></a><dl>
<dt><a name="index-process_002dwait"></a>Function: <strong>process-wait</strong> <em>[sb-ext] process &amp;optional check-for-stopped</em></dt>
<dd><p>Wait for <code>process</code> to quit running for some reason. When
<code>check-for-stopped</code> is <code>t</code>, also returns when <code>process</code> is stopped. Returns
<code>process</code>.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dexit_002dcode"></a><dl>
<dt><a name="index-process_002dexit_002dcode"></a>Function: <strong>process-exit-code</strong> <em>[sb-ext] process</em></dt>
<dd><p>The exit code or the signal of a stopped process.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dcore_002ddumped"></a><dl>
<dt><a name="index-process_002dcore_002ddumped"></a>Function: <strong>process-core-dumped</strong> <em>[sb-ext] instance</em></dt>
<dd><p><code>t</code> if a core image was dumped by the process.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dclose"></a><dl>
<dt><a name="index-process_002dclose"></a>Function: <strong>process-close</strong> <em>[sb-ext] process</em></dt>
<dd><p>Close all streams connected to <code>process</code> and stop maintaining the
status slot.
</p></dd></dl>

<a name="Function-sb_002dext_003aprocess_002dkill"></a><dl>
<dt><a name="index-process_002dkill"></a>Function: <strong>process-kill</strong> <em>[sb-ext] process signal &amp;optional whom</em></dt>
<dd><p>Hand <code>signal</code> to <code>process</code>. If <code>whom</code> is <code>:pid</code>, use the kill Unix system call. If
   <code>whom</code> is <code>:process-group</code>, use the killpg Unix system call. If <code>whom</code> is
   <code>:pty-process-group</code> deliver the signal to whichever process group is
   currently in the foreground.
</p></dd></dl>

<hr>
<a name="Unicode-Support"></a>
<div class="header">
<p>
Next: <a href="#Customization-Hooks-for-Users" accesskey="n" rel="next">Customization Hooks for Users</a>, Previous: <a href="#Support-For-Unix" accesskey="p" rel="prev">Support For Unix</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Unicode-Support-1"></a>
<h3 class="section">7.8 Unicode Support</h3>

<p>SBCL provides support for working with Unicode text and querying the
standard Unicode database for information about individual codepoints.
Unicode-related functions are located in the <code>sb-unicode</code> package.
</p>
<p>SBCL also extends ANSI character literal syntax to support Unicode
codepoints. You can either specify a character by its Unicode name, with
spaces replaced by underscores, if a unique name exists <a name="DOCF8" href="#FOOT8"><sup>8</sup></a> or
by giving its hexadecimal codepoint preceded by a &ldquo;U&rdquo;, an optional
&ldquo;+&rdquo;, and an arbitrary number of leading zeros. You may also input the
character directly into your source code if it can be encoded in your
file. If a character had an assigned name in Unicode 1.0 that was
distinct from its current name, you may also use that name (with spaces
replaced by underscores) to specify the character, unless the name is
already associated with a codepoint in the latest Unicode standard (such
as &ldquo;BELL&rdquo;).
</p>
<p>For example, you can specify the codepoint U+00E1 (&ldquo;Latin
Small Letter A With Acute&rdquo;) as
</p><ul>
<li> <code>#\LATIN_SMALL_LETTER_A_WITH_ACUTE</code>
</li><li> <code>#\LATIN_SMALL_LETTER_A_ACUTE</code>
</li><li> <code>#\á</code> assuming a Unicode source file
</li><li> <code>#\U00E1</code>
</li><li> <code>#\UE1</code>
</li><li> <code>#\U+00E1</code>
</li></ul>

<a name="Unicode-property-access"></a>
<h4 class="subsection">7.8.1 Unicode property access</h4>

<p>The following functions can be used to find information about a Unicode
codepoint.
</p>
<a name="Function-sb_002dunicode_003ageneral_002dcategory"></a><dl>
<dt><a name="index-general_002dcategory"></a>Function: <strong>general-category</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the general category of <code>character</code> as it appears in UnicodeData.txt
</p></dd></dl>

<a name="Function-sb_002dunicode_003abidi_002dclass"></a><dl>
<dt><a name="index-bidi_002dclass"></a>Function: <strong>bidi-class</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the bidirectional class of <code>character</code>
</p></dd></dl>

<a name="Function-sb_002dunicode_003acombining_002dclass"></a><dl>
<dt><a name="index-combining_002dclass"></a>Function: <strong>combining-class</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the canonical combining class (CCC) of <code>character</code>
</p></dd></dl>

<a name="Function-sb_002dunicode_003adecimal_002dvalue"></a><dl>
<dt><a name="index-decimal_002dvalue"></a>Function: <strong>decimal-value</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the decimal digit value associated with <code>character</code> or <code>nil</code> if
there is no such value.
</p>
<p>The only characters in Unicode with a decimal digit value are those
that are part of a range of characters that encode the digits 0-9.
Because of this, &lsquo;(decimal-digit c) &lt;=&gt; (digit-char-p c 10)&lsquo; in
#+sb-unicode builds
</p></dd></dl>

<a name="Function-sb_002dunicode_003adigit_002dvalue"></a><dl>
<dt><a name="index-digit_002dvalue"></a>Function: <strong>digit-value</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the Unicode digit value of <code>character</code> or <code>nil</code> if it doesn&rsquo;t exist.
</p>
<p>Digit values are guaranteed to be integers between 0 and 9 inclusive.
All characters with decimal digit values have the same digit value,
but there are characters (such as digits of number systems without a 0 value)
that have a digit value but no decimal digit value
</p></dd></dl>

<a name="Function-sb_002dunicode_003anumeric_002dvalue"></a><dl>
<dt><a name="index-numeric_002dvalue"></a>Function: <strong>numeric-value</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the numeric value of <code>character</code> or <code>nil</code> if there is no such value.
Numeric value is the most general of the Unicode numeric properties.
The only constraint on the numeric value is that it be a rational number.
</p></dd></dl>

<a name="Function-sb_002dunicode_003amirrored_002dp"></a><dl>
<dt><a name="index-mirrored_002dp"></a>Function: <strong>mirrored-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> needs to be mirrored in bidirectional text.
Otherwise, returns <code>nil</code>.
</p></dd></dl>

<a name="Function-sb_002dunicode_003abidi_002dmirroring_002dglyph"></a><dl>
<dt><a name="index-bidi_002dmirroring_002dglyph"></a>Function: <strong>bidi-mirroring-glyph</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the mirror image of <code>character</code> if it exists.
Otherwise, returns <code>nil</code>.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aage"></a><dl>
<dt><a name="index-age"></a>Function: <strong>age</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the version of Unicode in which <code>character</code> was assigned as a pair
of values, both integers, representing the major and minor version respectively.
If <code>character</code> is not assigned in Unicode, returns <code>nil</code> for both values.
</p></dd></dl>

<a name="Function-sb_002dunicode_003ahangul_002dsyllable_002dtype"></a><dl>
<dt><a name="index-hangul_002dsyllable_002dtype"></a>Function: <strong>hangul-syllable-type</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the Hangul syllable type of <code>character</code>.
The syllable type can be one of <code>:l</code>, <code>:v</code>, <code>:t</code>, <code>:lv</code>, or <code>:lvt</code>.
If the character is not a Hangul syllable or Jamo, returns <code>nil</code>
</p></dd></dl>

<a name="Function-sb_002dunicode_003aeast_002dasian_002dwidth"></a><dl>
<dt><a name="index-east_002dasian_002dwidth"></a>Function: <strong>east-asian-width</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the East Asian Width property of <code>character</code> as
one of the keywords <code>:n</code> (Narrow), <code>:a</code> (Ambiguous), <code>:h</code> (Halfwidth),
<code>:w</code> (Wide), <code>:f</code> (Fullwidth), or <code>:na</code> (Not applicable)
</p></dd></dl>

<a name="Function-sb_002dunicode_003ascript"></a><dl>
<dt><a name="index-script"></a>Function: <strong>script</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the Script property of <code>character</code> as a keyword.
If <code>character</code> does not have a known script, returns <code>:unknown</code>
</p></dd></dl>

<a name="Function-sb_002dunicode_003achar_002dblock"></a><dl>
<dt><a name="index-char_002dblock"></a>Function: <strong>char-block</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the Unicode block in which <code>character</code> resides as a keyword.
If <code>character</code> does not have a known block, returns <code>:no-block</code>
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_002d1_002dname"></a><dl>
<dt><a name="index-unicode_002d1_002dname"></a>Function: <strong>unicode-1-name</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns the name assigned to <code>character</code> in Unicode 1.0 if it is distinct
from the name currently assigned to <code>character</code>. Otherwise, returns <code>nil</code>.
This property has been officially obsoleted by the Unicode standard, and
is only included for backwards compatibility.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aproplist_002dp"></a><dl>
<dt><a name="index-proplist_002dp"></a>Function: <strong>proplist-p</strong> <em>[sb-unicode] character property</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has the specified <code>property</code>.
<code>property</code> is a keyword representing one of the properties from PropList.txt,
with underscores replaced by dashes.
</p></dd></dl>

<a name="Function-sb_002dunicode_003auppercase_002dp"></a><dl>
<dt><a name="index-uppercase_002dp"></a>Function: <strong>uppercase-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has the Unicode property Uppercase and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003alowercase_002dp"></a><dl>
<dt><a name="index-lowercase_002dp"></a>Function: <strong>lowercase-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has the Unicode property Lowercase and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003acased_002dp"></a><dl>
<dt><a name="index-cased_002dp"></a>Function: <strong>cased-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has a (Unicode) case, and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003acase_002dignorable_002dp"></a><dl>
<dt><a name="index-case_002dignorable_002dp"></a>Function: <strong>case-ignorable-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is Case Ignorable as defined in Unicode 6.3, Chapter
3
</p></dd></dl>

<a name="Function-sb_002dunicode_003aalphabetic_002dp"></a><dl>
<dt><a name="index-alphabetic_002dp"></a>Function: <strong>alphabetic-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is Alphabetic according to the Unicode standard
and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003aideographic_002dp"></a><dl>
<dt><a name="index-ideographic_002dp"></a>Function: <strong>ideographic-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has the Unicode property Ideographic,
which loosely corresponds to the set of &quot;Chinese characters&quot;
</p></dd></dl>

<a name="Function-sb_002dunicode_003amath_002dp"></a><dl>
<dt><a name="index-math_002dp"></a>Function: <strong>math-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is a mathematical symbol according to Unicode and
<code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003awhitespace_002dp"></a><dl>
<dt><a name="index-whitespace_002dp"></a>Function: <strong>whitespace-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is whitespace according to Unicode
and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003asoft_002ddotted_002dp"></a><dl>
<dt><a name="index-soft_002ddotted_002dp"></a>Function: <strong>soft-dotted-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> has a soft dot (such as the dots on i and j) which
disappears when accents are placed on top of it. and <code>nil</code> otherwise
</p></dd></dl>

<a name="Function-sb_002dunicode_003ahex_002ddigit_002dp"></a><dl>
<dt><a name="index-hex_002ddigit_002dp"></a>Function: <strong>hex-digit-p</strong> <em>[sb-unicode] character &amp;key ascii</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is a hexadecimal digit and <code>nil</code> otherwise.
If <code>:ascii</code> is non-NIL, fullwidth equivalents of the Latin letters A through <code>f</code>
are excluded.
</p></dd></dl>

<a name="Function-sb_002dunicode_003adefault_002dignorable_002dp"></a><dl>
<dt><a name="index-default_002dignorable_002dp"></a>Function: <strong>default-ignorable-p</strong> <em>[sb-unicode] character</em></dt>
<dd><p>Returns <code>t</code> if <code>character</code> is a Default_Ignorable_Code_Point
</p></dd></dl>

<a name="Function-sb_002dunicode_003agrapheme_002dbreak_002dclass"></a><dl>
<dt><a name="index-grapheme_002dbreak_002dclass"></a>Function: <strong>grapheme-break-class</strong> <em>[sb-unicode] char</em></dt>
<dd><p>Returns the grapheme breaking class of <code>character</code>, as specified in <code>uax</code> #29.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aword_002dbreak_002dclass"></a><dl>
<dt><a name="index-word_002dbreak_002dclass"></a>Function: <strong>word-break-class</strong> <em>[sb-unicode] char</em></dt>
<dd><p>Returns the word breaking class of <code>character</code>, as specified in <code>uax</code> #29.
</p></dd></dl>

<a name="Function-sb_002dunicode_003asentence_002dbreak_002dclass"></a><dl>
<dt><a name="index-sentence_002dbreak_002dclass"></a>Function: <strong>sentence-break-class</strong> <em>[sb-unicode] char</em></dt>
<dd><p>Returns the sentence breaking class of <code>character</code>, as specified in <code>uax</code> #29.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aline_002dbreak_002dclass"></a><dl>
<dt><a name="index-line_002dbreak_002dclass"></a>Function: <strong>line-break-class</strong> <em>[sb-unicode] character &amp;key resolve</em></dt>
<dd><p>Returns the line breaking class of <code>character</code>, as specified in <code>uax</code> #14.
If <code>:resolve</code> is <code>nil</code>, returns the character class found in the property file.
If <code>:resolve</code> is non-NIL, centain line-breaking classes will be mapped to othec
classes as specified in the applicable standards. Addinionally, if <code>:resolve</code>
is <code>:east-asian</code>, Ambigious (class :AI) characters will be mapped to the
Ideographic (:ID) class instead of Alphabetic (:AL).
</p></dd></dl>

<a name="String-operations"></a>
<h4 class="subsection">7.8.2 String operations</h4>

<p>SBCL can normalize strings using:
</p>
<a name="Function-sb_002dunicode_003anormalize_002dstring"></a><dl>
<dt><a name="index-normalize_002dstring"></a>Function: <strong>normalize-string</strong> <em>[sb-unicode] string &amp;optional form filter</em></dt>
<dd><p>Normalize <code>string</code> to the Unicode normalization form form.
Acceptable values for form are <code>:nfd</code>, <code>:nfc</code>, <code>:nfkd</code>, and <code>:nfkc</code>.
If <code>filter</code> is a function it is called on each decomposed character and
only characters for which it returns <code>t</code> are collected.
</p></dd></dl>

<a name="Function-sb_002dunicode_003anormalized_002dp"></a><dl>
<dt><a name="index-normalized_002dp"></a>Function: <strong>normalized-p</strong> <em>[sb-unicode] string &amp;optional form</em></dt>
<dd><p>Tests if <code>string</code> is normalized to <code>form</code>
</p></dd></dl>

<p>SBCL implements the full range of Unicode case operations with the
functions
</p>
<a name="Function-sb_002dunicode_003auppercase"></a><dl>
<dt><a name="index-uppercase"></a>Function: <strong>uppercase</strong> <em>[sb-unicode] string &amp;key locale</em></dt>
<dd><p>Returns the full uppercase of <code>string</code> according to the Unicode standard.
The result is not guaranteed to have the same length as the input. If <code>:locale</code>
is <code>nil</code>, no language-specific case transformations are applied. If <code>:locale</code> is a
keyword representing a two-letter <code>iso</code> country code, the case transforms of that
locale are used. If <code>:locale</code> is <code>t</code>, the user&rsquo;s current locale is used (Unix and
Win32 only).
</p></dd></dl>

<a name="Function-sb_002dunicode_003alowercase"></a><dl>
<dt><a name="index-lowercase"></a>Function: <strong>lowercase</strong> <em>[sb-unicode] string &amp;key locale</em></dt>
<dd><p>Returns the full lowercase of <code>string</code> according to the Unicode standard.
The result is not guaranteed to have the same length as the input.
<code>:locale</code> has the same semantics as the <code>:locale</code> argument to <code>uppercase</code>.
</p></dd></dl>

<a name="Function-sb_002dunicode_003atitlecase"></a><dl>
<dt><a name="index-titlecase"></a>Function: <strong>titlecase</strong> <em>[sb-unicode] string &amp;key locale</em></dt>
<dd><p>Returns the titlecase of <code>string</code>. The resulting string can
be longer than the input.
<code>:locale</code> has the same semantics as the <code>:locale</code> argument to <code>uppercase</code>.
</p></dd></dl>

<a name="Function-sb_002dunicode_003acasefold"></a><dl>
<dt><a name="index-casefold"></a>Function: <strong>casefold</strong> <em>[sb-unicode] string</em></dt>
<dd><p>Returns the full casefolding of <code>string</code> according to the Unicode standard.
Casefolding removes case information in a way that allows the results to be used
for case-insensitive comparisons.
The result is not guaranteed to have the same length as the input.
</p></dd></dl>

<p>It also extends standard Common Lisp case functions such as
<a name="index-string_002dupcase-_005bcl_005d"></a>
<code>string-upcase</code> and
<a name="index-char_002ddowncase-_005bcl_005d"></a>
<code>string-downcase</code> to support a subset of Unicode&rsquo;s casing behavior.
Specifically, a character is
<a name="index-both_002dcase_002dp-_005bcl_005d"></a>
<code>both-case-p</code> if its case mapping in Unicode is one-to-one and
invertable.
</p>
<p>The <code>sb-unicode</code> package also provides functions for
collating/sorting strings according to the Unicode Collation Algorithm.
</p>
<a name="Function-sb_002dunicode_003aunicode_003c"></a><dl>
<dt><a name="index-unicode_003c"></a>Function: <strong>unicode&lt;</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2</em></dt>
<dd><p>Determines whether STRING1 sorts before STRING2 using the Unicode Collation
Algorithm, The function uses an untailored Default Unicode Collation Element Table
to produce the sort keys. The function uses the Shifted method for dealing
with variable-weight characters, as described in <code>uts</code> #10
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_003d"></a><dl>
<dt><a name="index-unicode_003d"></a>Function: <strong>unicode=</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2 strict</em></dt>
<dd><p>Determines whether STRING1 and STRING2 are canonically equivalent according
to Unicode. The <code>start</code> and <code>end</code> arguments behave like the arguments to STRING=.
If <code>:strict</code> is <code>nil</code>, UNICODE= tests compatibility equavalence instead.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_002dequal"></a><dl>
<dt><a name="index-unicode_002dequal"></a>Function: <strong>unicode-equal</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2 strict</em></dt>
<dd><p>Determines whether STRING1 and STRING2 are canonically equivalent after
casefoldin8 (that is, ignoring case differences) according to Unicode. The
<code>start</code> and <code>end</code> arguments behave like the arguments to STRING=. If <code>:strict</code> is
<code>nil</code>, UNICODE= tests compatibility equavalence instead.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_003c_003d"></a><dl>
<dt><a name="index-unicode_003c_003d"></a>Function: <strong>unicode&lt;=</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2</em></dt>
<dd><p>Tests if STRING1 and STRING2 are either UNICODE&lt; or UNICODE=
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_003e"></a><dl>
<dt><a name="index-unicode_003e"></a>Function: <strong>unicode&gt;</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2</em></dt>
<dd><p>Tests if STRING2 is UNICODE&lt; STRING1.
</p></dd></dl>

<a name="Function-sb_002dunicode_003aunicode_003e_003d"></a><dl>
<dt><a name="index-unicode_003e_003d"></a>Function: <strong>unicode&gt;=</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2</em></dt>
<dd><p>Tests if STRING1 and STRING2 are either UNICODE= or UNICODE&gt;
</p></dd></dl>

<p>The following functions are provided for detecting visually confusable strings:
</p>
<a name="Function-sb_002dunicode_003aconfusable_002dp"></a><dl>
<dt><a name="index-confusable_002dp"></a>Function: <strong>confusable-p</strong> <em>[sb-unicode] string1 string2 &amp;key start1 end1 start2 end2</em></dt>
<dd><p>Determines whether STRING1 and STRING2 could be visually confusable
according to the <code>idna</code> confusableSummary.txt table
</p></dd></dl>

<a name="Breaking-strings"></a>
<h4 class="subsection">7.8.3 Breaking strings</h4>

<p>The <code>sb-unicode</code> package includes several functions for breaking a
Unicode string into useful parts.
</p>
<a name="Function-sb_002dunicode_003agraphemes"></a><dl>
<dt><a name="index-graphemes"></a>Function: <strong>graphemes</strong> <em>[sb-unicode] string</em></dt>
<dd><p>Breaks <code>string</code> into graphemes acording to the default
grapheme breaking rules specified in <code>uax</code> #29, returning a list of strings.
</p></dd></dl>

<a name="Function-sb_002dunicode_003awords"></a><dl>
<dt><a name="index-words"></a>Function: <strong>words</strong> <em>[sb-unicode] string</em></dt>
<dd><p>Breaks <code>string</code> into words acording to the default
word breaking rules specified in <code>uax</code> #29. Returns a list of strings
</p></dd></dl>

<a name="Function-sb_002dunicode_003asentences"></a><dl>
<dt><a name="index-sentences"></a>Function: <strong>sentences</strong> <em>[sb-unicode] string</em></dt>
<dd><p>Breaks <code>string</code> into sentences acording to the default
sentence breaking rules specified in <code>uax</code> #29
</p></dd></dl>

<a name="Function-sb_002dunicode_003alines"></a><dl>
<dt><a name="index-lines"></a>Function: <strong>lines</strong> <em>[sb-unicode] string &amp;key margin</em></dt>
<dd><p>Breaks <code>string</code> into lines that are no wider than <code>:margin</code> according to the
line breaking rules outlined in <code>uax</code> #14. Combining marks will always be kept
together with their base characters, and spaces (but not other types of
whitespace) will be removed from the end of lines. If <code>:margin</code> is unspecified,
it defaults to 80 characters
</p></dd></dl>

<hr>
<a name="Customization-Hooks-for-Users"></a>
<div class="header">
<p>
Next: <a href="#Tools-To-Help-Developers" accesskey="n" rel="next">Tools To Help Developers</a>, Previous: <a href="#Unicode-Support" accesskey="p" rel="prev">Unicode Support</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Customization-Hooks-for-Users-1"></a>
<h3 class="section">7.9 Customization Hooks for Users</h3>

<p>The toplevel repl prompt may be customized, and the function
that reads user input may be replaced completely.
</p>
<p>The behaviour of <code>require</code> when called with only one argument is
implementation-defined.  In SBCL, <code>require</code> behaves in the
following way:
</p>
<a name="Function-common_002dlisp_003arequire"></a><dl>
<dt><a name="index-require"></a>Function: <strong>require</strong> <em>[cl] module-name &amp;optional pathnames</em></dt>
<dd><p>Loads a module, unless it already has been loaded. <code>pathnames</code>, if supplied,
   is a designator for a list of pathnames to be loaded if the module
   needs to be. If <code>pathnames</code> is not supplied, functions from the list
   <code>*module-provider-functions*</code> are called in order with <code>module-name</code>
   as an argument, until one of them returns non-NIL.  User code is
   responsible for calling <code>provide</code> to indicate a successful load of the
   module.
</p></dd></dl>
<a name="Variable-sb_002dext_003a_002amodule_002dprovider_002dfunctions_002a"></a><dl>
<dt><a name="index-_002amodule_002dprovider_002dfunctions_002a"></a>Variable: <strong>*module-provider-functions*</strong> <em>[sb-ext]</em></dt>
<dd><p>See function documentation for <code>require</code>.
</p></dd></dl>

<p>Although SBCL does not provide a resident editor, the <code>ed</code>
function can be customized to hook into user-provided editing
mechanisms as follows:
</p>
<a name="Function-common_002dlisp_003aed"></a><dl>
<dt><a name="index-ed"></a>Function: <strong>ed</strong> <em>[cl] &amp;optional x</em></dt>
<dd><p>Starts the editor (on a file or a function if named).  Functions
from the list <code>*ed-functions*</code> are called in order with <code>x</code> as an argument
until one of them returns non-NIL; these functions are responsible for
signalling a <code>file-error</code> to indicate failure to perform an operation on
the file system.
</p></dd></dl>
<a name="Variable-sb_002dext_003a_002aed_002dfunctions_002a"></a><dl>
<dt><a name="index-_002aed_002dfunctions_002a"></a>Variable: <strong>*ed-functions*</strong> <em>[sb-ext]</em></dt>
<dd><p>See function documentation for <code>ed</code>.
</p></dd></dl>

<p>Conditions of type <code>warning</code> and <code>style-warning</code> are
sometimes signaled at runtime, especially during execution of Common
Lisp defining forms such as <code>defun</code>, <code>defmethod</code>, etc.  To
muffle these warnings at runtime, SBCL provides a variable
<code>sb-ext:*muffled-warnings*</code>:
</p>
<a name="Variable-sb_002dext_003a_002amuffled_002dwarnings_002a"></a><dl>
<dt><a name="index-_002amuffled_002dwarnings_002a"></a>Variable: <strong>*muffled-warnings*</strong> <em>[sb-ext]</em></dt>
<dd><p>A type that ought to specify a subtype of <code>warning</code>.  Whenever a
warning is signaled, if the warning is of this type and is not
handled by any other handler, it will be muffled.
</p></dd></dl>

<hr>
<a name="Tools-To-Help-Developers"></a>
<div class="header">
<p>
Next: <a href="#Resolution-of-Name-Conflicts" accesskey="n" rel="next">Resolution of Name Conflicts</a>, Previous: <a href="#Customization-Hooks-for-Users" accesskey="p" rel="prev">Customization Hooks for Users</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Tools-To-Help-Developers-1"></a>
<h3 class="section">7.10 Tools To Help Developers</h3>
<a name="index-trace-_005bcl_005d"></a>
<a name="index-inspect-_005bcl_005d"></a>

<p>SBCL provides a profiler and other extensions to the ANSI <code>trace</code>
facility.  For more information, see <a href="#Macro-common_002dlisp_003atrace">Macro common-lisp:trace</a>.
</p>
<p>The debugger supports a number of options. Its documentation is
accessed by typing <kbd>help</kbd> at the debugger prompt. See <a href="#Debugger">Debugger</a>.
</p>
<p>Documentation for <code>inspect</code> is accessed by typing <kbd>help</kbd> at
the <code>inspect</code> prompt.
</p>
<hr>
<a name="Resolution-of-Name-Conflicts"></a>
<div class="header">
<p>
Next: <a href="#Hash-Table-Extensions" accesskey="n" rel="next">Hash Table Extensions</a>, Previous: <a href="#Tools-To-Help-Developers" accesskey="p" rel="prev">Tools To Help Developers</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Resolution-of-Name-Conflicts-1"></a>
<h3 class="section">7.11 Resolution of Name Conflicts</h3>
<a name="index-name_002dconflict-_005bsb_002dext_005d"></a>
<a name="index-name_002dconflict_002dsymbols-_005bsb_002dext_005d"></a>

<p>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 <code>sb-ext:resolve-conflict</code> restart should be invoked with one
argument, which should be a member of the list returned by the condition
accessor <code>sb-ext:name-conflict-symbols</code>.
</p>
<hr>
<a name="Hash-Table-Extensions"></a>
<div class="header">
<p>
Next: <a href="#Random-Number-Generation" accesskey="n" rel="next">Random Number Generation</a>, Previous: <a href="#Resolution-of-Name-Conflicts" accesskey="p" rel="prev">Resolution of Name Conflicts</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Hash-Table-Extensions-1"></a>
<h3 class="section">7.12 Hash Table Extensions</h3>
<a name="index-Hash-tables"></a>

<p>Hash table extensions supported by SBCL are all controlled by keyword
arguments to <code>make-hash-table</code>.
</p>
<a name="Function-common_002dlisp_003amake_002dhash_002dtable"></a><dl>
<dt><a name="index-make_002dhash_002dtable"></a>Function: <strong>make-hash-table</strong> <em>[cl] &amp;key test size rehash-size rehash-threshold hash-function weakness synchronized</em></dt>
<dd><p>Create and return a new hash table. The keywords are as follows:
</p>

<dl compact="compact">
<dt><em><code>:test</code></em></dt>
<dd><p>Determines how keys are compared. Must a designator for one of the
    standard hash table tests, or a hash table test defined using
    <code>sb-ext:define-hash-table-test</code>. Additionally, when an explicit
    <code>hash-function</code> is provided (see below), any two argument equivalence
    predicate can be used as the <code>test</code>.
</p>

</dd>
<dt><em><code>:size</code></em></dt>
<dd><p>A hint as to how many elements will be put in this hash table.
</p>

</dd>
<dt><em><code>:rehash-size</code></em></dt>
<dd><p>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.
</p>

</dd>
<dt><em><code>:rehash-threshold</code></em></dt>
<dd><p>Indicates how dense the table can become before forcing a rehash. Can be
    any positive number &lt;=1, with density approaching zero as the threshold
    approaches 0. Density 1 means an average of one entry per bucket.
</p>

</dd>
<dt><em><code>:hash-function</code></em></dt>
<dd><p>If <code>nil</code> (the default), a hash function based on the <code>test</code> 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
    <code>sb-ext:define-hash-table-test</code>. If <code>hash-function</code> is specified, the <code>test</code>
    argument can be any two argument predicate consistent with it. The
    <code>hash-function</code> is expected to return a non-negative fixnum hash code.
</p>

</dd>
<dt><em><code>:weakness</code></em></dt>
<dd><p>When <code>:weakness</code> is not <code>nil</code>, garbage collection may remove entries from the
    hash table. The value of <code>:weakness</code> specifies how the presence of a key or
    value in the hash table preserves their entries from garbage collection.
</p>
<p>Valid values are:
</p>
<p><code>:key</code> means that the key of an entry must be live to guarantee that the
        entry is preserved.
</p>
<p><code>:value</code> means that the value of an entry must be live to guarantee that
        the entry is preserved.
</p>
<p><code>:key-and-value</code> means that both the key and the value must be live to
        guarantee that the entry is preserved.
</p>
<p><code>:key-or-value</code> means that either the key or the value must be live to
        guarantee that the entry is preserved.
</p>
<p><code>nil</code> (the default) means that entries are always preserved.
</p>

</dd>
<dt><em><code>:synchronized</code></em></dt>
<dd><p>If <code>nil</code> (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 <code>t</code>, all concurrent accesses
    are safe, but note that <code>clhs</code> 3.6 (Traversal Rules and Side Effects)
    remains in force. See also: <code>sb-ext:with-locked-hash-table</code>. This keyword
    argument is experimental, and may change incompatibly or be removed in the
    future.
</p></dd>
</dl>

</dd></dl>

<a name="Macro-sb_002dext_003adefine_002dhash_002dtable_002dtest"></a><dl>
<dt><a name="index-define_002dhash_002dtable_002dtest"></a>Macro: <strong>define-hash-table-test</strong> <em>[sb-ext] name hash-function</em></dt>
<dd><p>Defines <code>name</code> as a new kind of hash table test for use with the <code>:test</code>
argument to <code>make-hash-table</code>, and associates a default <code>hash-function</code> with it.
</p>
<p><code>name</code> must be a symbol naming a global two argument equivalence predicate.
Afterwards both <code>'name</code> and <code>#'name</code> can be used with <code>:test</code> argument. In both
cases <code>hash-table-test</code> will return the symbol <code>name</code>.
</p>
<p><code>hash-function</code> must be a symbol naming a global hash function consistent with
the predicate, or be a <code>lambda</code> form implementing one in the current lexical
environment. The hash function must compute the same hash code for any two
objects for which <code>name</code> returns true, and subsequent calls with already hashed
objects must always return the same hash code.
</p>
<p>Note: The <code>:hash-function</code> keyword argument to <code>make-hash-table</code> can be used to
override the specified default hash-function.
</p>
<p>Attempting to define <code>name</code> in a locked package as hash-table test causes a
package lock violation.
</p>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">  ;;; 1.

  ;; We want to use objects of type FOO as keys (by their
  ;; names.) EQUALP would work, but would make the names
  ;; case-insensitive -- which 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)                   =&gt; T
      ;;   (= (SXHASH 1) (SXHASH 1.0)) =&gt; 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 '==))
</pre></div>
</dd></dl>

<a name="Macro-sb_002dext_003awith_002dlocked_002dhash_002dtable"></a><dl>
<dt><a name="index-with_002dlocked_002dhash_002dtable"></a>Macro: <strong>with-locked-hash-table</strong> <em>[sb-ext] (hash-table) &amp;body body</em></dt>
<dd><p>Limits concurrent accesses to <code>hash-table</code> for the duration of <code>body</code>.
If <code>hash-table</code> is synchronized, <code>body</code> will execute with exclusive
ownership of the table. If <code>hash-table</code> is not synchronized, <code>body</code> will
execute with other <code>with-locked-hash-table</code> bodies excluded <code>--</code> exclusion
of hash-table accesses not surrounded by <code>with-locked-hash-table</code> is
unspecified.
</p></dd></dl>

<a name="Function-sb_002dext_003ahash_002dtable_002dsynchronized_002dp"></a><dl>
<dt><a name="index-hash_002dtable_002dsynchronized_002dp"></a>Function: <strong>hash-table-synchronized-p</strong> <em>[sb-ext] instance</em></dt>
<dd><p>Returns <code>t</code> if <code>hash-table</code> is synchronized.
</p></dd></dl>

<a name="Function-sb_002dext_003ahash_002dtable_002dweakness"></a><dl>
<dt><a name="index-hash_002dtable_002dweakness"></a>Function: <strong>hash-table-weakness</strong> <em>[sb-ext] instance</em></dt>
<dd><p>Return the <code>weakness</code> of <code>hash-table</code> which is one of <code>nil</code>, <code>:key</code>,
<code>:value</code>, <code>:key-and-value</code>, <code>:key-or-value</code>.
</p></dd></dl>

<hr>
<a name="Random-Number-Generation"></a>
<div class="header">
<p>
Next: <a href="#Miscellaneous-Extensions" accesskey="n" rel="next">Miscellaneous Extensions</a>, Previous: <a href="#Hash-Table-Extensions" accesskey="p" rel="prev">Hash Table Extensions</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Random-Number-Generation-1"></a>
<h3 class="section">7.13 Random Number Generation</h3>
<a name="index-Random-Number-Generation"></a>

<p>The initial value of <code>*random-state*</code> is the same each time SBCL
is started. This makes it possible for user code to obtain repeatable
pseudo random numbers using only standard-provided functionality. See
<code>seed-random-state</code> below for an SBCL extension that allows to
seed the random number generator from given data for an additional
possibility to achieve this. Non-repeatable random numbers can always
be obtained using <code>(make-random-state t)</code>.
</p>
<p>The sequence of numbers produced by repeated calls to <code>random</code>
starting with the same random state and using the same sequence of
<code>limit</code> arguments is guaranteed to be reproducible only in the
same version of SBCL on the same platform, using the same code under
the same evaluator mode and compiler optimization qualities. Just two
examples of differences that may occur otherwise: calls to
<code>random</code> can be compiled differently depending on how much is
known about the <code>limit</code> argument at compile time, yielding
different results even if called with the same argument at run time,
and the results can differ depending on the machine&rsquo;s word size, for
example for limits that are fixnums under 64-bit word size but bignums
under 32-bit word size.
</p>
<a name="Function-sb_002dext_003aseed_002drandom_002dstate"></a><dl>
<dt><a name="index-seed_002drandom_002dstate"></a>Function: <strong>seed-random-state</strong> <em>[sb-ext] &amp;optional state</em></dt>
<dd><p>Make a random state object. The optional <code>state</code> argument specifies a seed
for deterministic pseudo-random number generation.
</p>
<p>As per the Common Lisp standard for <code>make-random-state</code>,
</p><ul>
<li> If <code>state</code> is <code>nil</code> or not supplied, return a copy of the default
  <code>*random-state*</code>.
</li><li> If <code>state</code> is a random state, return a copy of it.
</li><li> If <code>state</code> is <code>t</code>, return a randomly initialized state (using operating-system
  provided randomness where available, otherwise a poor substitute based on
  internal time and pid).

</li></ul>
<p>As a supported <code>sbcl</code> extension, we also support receiving as a seed an object
of the following types:
</p><ul>
<li> <code>(simple-array (unsigned-byte 8) (*))</code>
</li><li> <code>unsigned-byte</code>
</li></ul>
<p>While we support arguments of any size and will mix the provided bits into
the random state, it is probably overkill to provide more than 256 bits worth
of actual information.
</p>
<p>This particular <code>sbcl</code> version also accepts an argument of the following type:
<code>(simple-array (unsigned-byte 32) (*))</code>
</p>
<p>This particular <code>sbcl</code> version uses the popular MT19937 <code>prng</code> algorithm, and its
internal state only effectively contains about 19937 bits of information.
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
</p></dd></dl>

<p>Some notes on random floats: The standard doesn&rsquo;t prescribe a specific
method of generating random floats. The following paragraph describes
SBCL&rsquo;s current implementation and should be taken purely informational,
that is, user code should not depend on any of its specific properties.
The method used has been chosen because it is common, conceptually
simple and fast.
</p>
<p>To generate random floats, SBCL evaluates code that has an equivalent
effect as
</p><div class="lisp">
<pre class="lisp">(* limit
   (float (/ (random (expt 2 23)) (expt 2 23)) 1.0f0))
</pre></div>
<p>(for single-floats) and correspondingly (with <code>52</code> and
<code>1.0d0</code> instead of <code>23</code> and <code>1.0f0</code>) for double-floats.
Note especially that this means that zero is a possible return value
occurring with probability <code>(expt 2 -23)</code> respectively
<code>(expt 2 -52)</code>. Also note that there exist twice as many
equidistant floats between 0 and 1 as are generated. For example, the
largest number that <code>(random 1.0f0)</code> ever returns is
<code>(float (/ (1- (expt 2 23)) (expt 2 23)) 1.0f0)</code> while
<code>(float (/ (1- (expt 2 24)) (expt 2 24)) 1.0f0)</code> is the
largest single-float less than 1. This is a side effect of the fact
that the implementation uses the fastest possible conversion from bits
to floats.
</p>
<p>SBCL currently uses the Mersenne Twister as its random number
generator, specifically the 32-bit version under both 32- and 64-bit
word size. The seeding algorithm has been improved several times by
the authors of the Mersenne Twister; SBCL uses the third version
(from 2002) which is still the most recent as of June 2012. The
implementation has been tested to provide output identical to the
recommended C implementation.
</p>
<p>While the Mersenne Twister generates random numbers of much better
statistical quality than other widely used generators, it uses only
linear operations modulo 2 and thus fails some statistical
tests<a name="DOCF9" href="#FOOT9"><sup>9</sup></a>.
For example, the distribution of ranks of (sufficiently large) random
binary matrices is much distorted compared to the theoretically
expected one when the matrices are generated by the Mersenne Twister.
Thus, applications that are sensitive to this aspect should use a
different type of generator.
</p>
<hr>
<a name="Miscellaneous-Extensions"></a>
<div class="header">
<p>
Next: <a href="#Stale-Extensions" accesskey="n" rel="next">Stale Extensions</a>, Previous: <a href="#Random-Number-Generation" accesskey="p" rel="prev">Random Number Generation</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Miscellaneous-Extensions-1"></a>
<h3 class="section">7.14 Miscellaneous Extensions</h3>

<a name="Function-sb_002dext_003aarray_002dstorage_002dvector"></a><dl>
<dt><a name="index-array_002dstorage_002dvector"></a>Function: <strong>array-storage-vector</strong> <em>[sb-ext] array</em></dt>
<dd><p>Returns the underlying storage vector of <code>array</code>, which must be a non-displaced array.
</p>
<p>In <code>sbcl</code>, if <code>array</code> is a of type <code>(simple-array * (*))</code>, it is its own storage
vector. Multidimensional arrays, arrays with fill pointers, and adjustable
arrays have an underlying storage vector with the same <code>array-element-type</code> as
<code>array</code>, which this function returns.
</p>
<p>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.
</p></dd></dl>
<a name="Function-sb_002dext_003adelete_002ddirectory"></a><dl>
<dt><a name="index-delete_002ddirectory"></a>Function: <strong>delete-directory</strong> <em>[sb-ext] pathspec &amp;key recursive</em></dt>
<dd><p>Deletes the directory designated by <code>pathspec</code> (a pathname designator).
Returns the truename of the directory deleted.
</p>
<p>If <code>recursive</code> is false (the default), signals an error unless the directory is
empty. If <code>recursive</code> is true, first deletes all files and subdirectories. If
<code>recursive</code> is true and the directory contains symbolic links, the links are
deleted, not the files and directories they point to.
</p>
<p>Signals an error if <code>pathspec</code> designates a file or a symbolic link instead of a
directory, or if the directory could not be deleted for any reason.
</p>
<p>Both
</p>
<div class="lisp">
<pre class="lisp">   (DELETE-DIRECTORY &quot;/tmp/foo&quot;)
   (DELETE-DIRECTORY &quot;/tmp/foo/&quot;)
</pre></div>

<p>delete the &quot;foo&quot; subdirectory of &quot;/tmp&quot;, or signal an error if it does not
exist or if is a file or a symbolic link.
</p></dd></dl>
<a name="Function-sb_002dext_003aget_002dtime_002dof_002dday"></a><dl>
<dt><a name="index-get_002dtime_002dof_002dday"></a>Function: <strong>get-time-of-day</strong> <em>[sb-ext]</em></dt>
<dd><p>Return the number of seconds and microseconds since the beginning of
the <code>unix</code> epoch (January 1st 1970.)
</p></dd></dl>
<a name="Macro-sb_002dext_003await_002dfor"></a><dl>
<dt><a name="index-wait_002dfor"></a>Macro: <strong>wait-for</strong> <em>[sb-ext] test-form &amp;key timeout</em></dt>
<dd><p>Wait until <code>test-form</code> evaluates to true, then return its primary value.
If <code>timeout</code> is provided, waits at most approximately <code>timeout</code> seconds before
returning <code>nil</code>.
</p>
<p>If <code>with-deadline</code> has been used to provide a global deadline, signals a
<code>deadline-timeout</code> if <code>test-form</code> doesn&rsquo;t evaluate to true before the
deadline.
</p>
<p>Experimental: subject to change without prior notice.
</p></dd></dl>
<a name="Function-sb_002dext_003aassert_002dversion_002d_003e_003d"></a><dl>
<dt><a name="index-assert_002dversion_002d_003e_003d"></a>Function: <strong>assert-version-&gt;=</strong> <em>[sb-ext] &amp;rest subversions</em></dt>
<dd><p>Asserts that the current <code>sbcl</code> is of version equal to or greater than
the version specified in the arguments.  A continuable error is signaled
otherwise.
</p>
<p>The arguments specify a sequence of subversion numbers in big endian order.
They are compared lexicographically with the runtime version, and versions
are treated as though trailed by an unbounded number of 0s.
</p>
<p>For example, (assert-version-&gt;= 1 1 4) asserts that the current <code>sbcl</code> is
version 1.1.4[.0.0...] or greater, and (assert-version-&gt;= 1) that it is
version 1[.0.0...] or greater.
</p></dd></dl>

<hr>
<a name="Stale-Extensions"></a>
<div class="header">
<p>
Next: <a href="#Efficiency-Hacks" accesskey="n" rel="next">Efficiency Hacks</a>, Previous: <a href="#Miscellaneous-Extensions" accesskey="p" rel="prev">Miscellaneous Extensions</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Stale-Extensions-1"></a>
<h3 class="section">7.15 Stale Extensions</h3>

<p>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 <samp>src/code/gc.lisp</samp>
and bring it up on the developers&rsquo; mailing list.
</p>
<p>SBCL has various hooks inherited from CMUCL, like
<code>sb-ext:float-denormalized-p</code>, to allow a program to take
advantage of IEEE floating point arithmetic properties which aren&rsquo;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&rsquo;t in the ANSI spec and it didn&rsquo;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&rsquo; mailing
list.
</p>

<hr>
<a name="Efficiency-Hacks"></a>
<div class="header">
<p>
Previous: <a href="#Stale-Extensions" accesskey="p" rel="prev">Stale Extensions</a>, Up: <a href="#Beyond-the-ANSI-Standard" accesskey="u" rel="up">Beyond the ANSI Standard</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Efficiency-Hacks-1"></a>
<h3 class="section">7.16 Efficiency Hacks</h3>

<p>The <code>sb-ext:purify</code> 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&rsquo;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.
</p>
<a name="Function-sb_002dext_003apurify"></a><dl>
<dt><a name="index-purify"></a>Function: <strong>purify</strong> <em>[sb-ext] &amp;key root-structures environment-name</em></dt>
<dd><p>This function optimizes garbage collection by moving all currently live
   objects into non-collected storage. <code>root-structures</code> is an optional list of
   objects which should be copied first to maximize locality.
</p>
<p><code>defstruct</code> structures defined with the <code>(:pure t) </code>option are moved into
   read-only storage, further reducing <code>gc</code> cost. List and vector slots of pure
   structures are also moved into read-only storage.
</p>
<p><code>environment-name</code> is unused.
</p>
<p>This function is a no-op on platforms using the generational garbage
   collector (x86, x86-64, ppc, arm, arm64).
</p></dd></dl>

<p>The <code>sb-ext:truly-the</code> special form declares the type of the
result of the operations, producing its argument; the declaration is
not checked. In short: don&rsquo;t use it.
</p>
<a name="Special_002dOperator-sb_002dext_003atruly_002dthe"></a><dl>
<dt><a name="index-truly_002dthe"></a>Special Operator: <strong>truly-the</strong> <em>[sb-ext] value-type form</em></dt>
<dd><p>Specifies that the values returned by <code>form</code> conform to the
<code>value-type</code>, and causes the compiler to trust this information
unconditionally.
</p>
<p>Consequences are undefined if any result is not of the declared type
<code>--</code> typical symptoms including memory corruptions. Use with great
care.
</p></dd></dl>

<p>The <code>sb-ext:freeze-type</code> declaration declares that a
type will never change, which can make type testing
(<code>typep</code>, etc.) more efficient for structure types.
</p><hr>
<a name="Foreign-Function-Interface"></a>
<div class="header">
<p>
Next: <a href="#Pathnames" accesskey="n" rel="next">Pathnames</a>, Previous: <a href="#Beyond-the-ANSI-Standard" accesskey="p" rel="prev">Beyond the ANSI Standard</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Function-Interface-1"></a>
<h2 class="chapter">8 Foreign Function Interface</h2>

<p>This chapter describes SBCL&rsquo;s interface to C programs and
libraries (and, since C interfaces are a sort of <em>lingua
franca</em> of the Unix world, to other programs and libraries in
general.)
</p>
<blockquote>
<p>Note: In the modern Lisp world, the usual term for this functionality
is Foreign Function Interface, or <acronym>FFI</acronym>, where despite the
mention of &ldquo;function&rdquo; in this term, <acronym>FFI</acronym> 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 <code>SB-ALIEN</code> package.
</p></blockquote>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Introduction-to-the-Foreign-Function-Interface" accesskey="1">Introduction to the Foreign Function Interface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Types" accesskey="2">Foreign Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Operations-On-Foreign-Values" accesskey="3">Operations On Foreign Values</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Variables" accesskey="4">Foreign Variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Data-Structure-Examples" accesskey="5">Foreign Data Structure Examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Loading-Shared-Object-Files" accesskey="6">Loading Shared Object Files</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Function-Calls" accesskey="7">Foreign Function Calls</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface" accesskey="8">Step-By-Step Example of the Foreign Function Interface</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Introduction-to-the-Foreign-Function-Interface"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Types" accesskey="n" rel="next">Foreign Types</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Introduction-to-the-Foreign-Function-Interface-1"></a>
<h3 class="section">8.1 Introduction to the Foreign Function Interface</h3>

<p>Because of Lisp&rsquo;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:
</p>
<ul>
<li> 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
&ldquo;glue&rdquo; code on the C side, and that code tends to be sensitively
dependent on the internal implementation details of the Lisp system.

</li><li> 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
<acronym>FFI</acronym>, and used automatically when passing integers and strings.

</li><li> The Lisp program can directly manipulate foreign objects through the
use of extensions to the Lisp language.

</li></ul>

<p>SBCL, like CMUCL before it, relies primarily on the automatic
conversion and direct manipulation approaches. The <code>SB-ALIEN</code>
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 <acronym>SAP</acronym>s) can be used where
necessary to provide untyped access to foreign memory.
</p>
<p>Any foreign objects that can&rsquo;t automatically be converted into Lisp
values are represented by objects of type <code>alien-value</code>.  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 <code>alien-value</code> object.
</p>
<p>The type language and operations on foreign types are
intentionally similar to those of the C language.
</p>
<hr>
<a name="Foreign-Types"></a>
<div class="header">
<p>
Next: <a href="#Operations-On-Foreign-Values" accesskey="n" rel="next">Operations On Foreign Values</a>, Previous: <a href="#Introduction-to-the-Foreign-Function-Interface" accesskey="p" rel="prev">Introduction to the Foreign Function Interface</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Types-1"></a>
<h3 class="section">8.2 Foreign Types</h3>

<p>Alien types have a description language based on nested list
structure. For example the C type
</p>
<div class="example">
<pre class="example">struct foo {
    int a;
    struct foo *b[100];
};
</pre></div>

<p>has the corresponding SBCL <acronym>FFI</acronym> type
</p>
<div class="lisp">
<pre class="lisp">(struct foo
  (a int)
  (b (array (* (struct foo)) 100)))
</pre></div>


<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Defining-Foreign-Types" accesskey="1">Defining Foreign Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Types-and-Lisp-Types" accesskey="2">Foreign Types and Lisp Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Type-Specifiers" accesskey="3">Foreign Type Specifiers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Defining-Foreign-Types"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Types-and-Lisp-Types" accesskey="n" rel="next">Foreign Types and Lisp Types</a>, Up: <a href="#Foreign-Types" accesskey="u" rel="up">Foreign Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Defining-Foreign-Types-1"></a>
<h4 class="subsection">8.2.1 Defining Foreign Types</h4>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(struct foo (a (* (struct foo))))
</pre></div>

<p>An anonymous structure or union type is specified by using the name
<code>nil</code>.  The <code>with-alien</code> macro defines a local scope which
&ldquo;captures&rdquo; any named type definitions.  Other types are not
inherently named, but can be given named abbreviations using the
<code>define-alien-type</code> macro.
</p>
<hr>
<a name="Foreign-Types-and-Lisp-Types"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Type-Specifiers" accesskey="n" rel="next">Foreign Type Specifiers</a>, Previous: <a href="#Defining-Foreign-Types" accesskey="p" rel="prev">Defining Foreign Types</a>, Up: <a href="#Foreign-Types" accesskey="u" rel="up">Foreign Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Types-and-Lisp-Types-1"></a>
<h4 class="subsection">8.2.2 Foreign Types and Lisp Types</h4>

<p>The foreign types form a subsystem of the SBCL type system.  An
<code>alien</code> type specifier provides a way to use any foreign type as a
Lisp type specifier.  For example,
</p>
<div class="lisp">
<pre class="lisp">(typep <var>foo</var> '(alien (* int)))
</pre></div>

<p>can be used to determine whether <var>foo</var> is a pointer to a foreign
<code>int</code>. <code>alien</code> type specifiers can be used in the same ways
as ordinary Lisp type specifiers (like <code>string</code>.) Alien type
declarations are subject to the same precise type checking as any
other declaration.  See <a href="#Precise-Type-Checking">Precise Type Checking</a>.
</p>
<p>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 <code>(alien single-float)</code> is identical to
<code>single-float</code>, since foreign floats are automatically converted
to Lisp floats.  When <code>type-of</code> is called on an alien value that
is not automatically converted to a Lisp value, then it will return an
<code>alien</code> type specifier.
</p>
<hr>
<a name="Foreign-Type-Specifiers"></a>
<div class="header">
<p>
Previous: <a href="#Foreign-Types-and-Lisp-Types" accesskey="p" rel="prev">Foreign Types and Lisp Types</a>, Up: <a href="#Foreign-Types" accesskey="u" rel="up">Foreign Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Type-Specifiers-1"></a>
<h4 class="subsection">8.2.3 Foreign Type Specifiers</h4>

<p>Note: All foreign type names are exported from the <code>sb-alien</code>
package. Some foreign type names are also symbols in
the <code>common-lisp</code> package, in which case they are
reexported from the <code>sb-alien</code> package, so that
e.g. it is legal to refer to <code>sb-alien:single-float</code>.
</p>
<p>These are the basic foreign type specifiers:
</p>
<ul>
<li> The foreign type specifier <code>(* <var>foo</var>)</code> describes a pointer to
an object of type <var>foo</var>.  A pointed-to type <var>foo</var> of <code>t</code>
indicates a pointer to anything, similar to <code>void *</code> in
ANSI C. A null alien pointer can be detected with the
<code>sb-alien:null-alien</code> function.

</li><li> The foreign type specifier <code>(array <var>foo</var> &amp;rest
dimensions)</code> describes array of the specified <code>dimensions</code>,
holding elements of type <var>foo</var>. Note that (unlike in C) <code>(*
<var>foo</var>)</code> and <code>(array <var>foo</var>)</code> 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
<code>sb-alien:cast</code>.

<p>Arrays are accessed using <code>sb-alien:deref</code>, 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 <code>nil</code>
as the first dimension.  Fixed-size arrays can be allocated as array
elements, structure slots or <code>sb-alien:with-alien</code>
variables. Dynamic arrays can only be allocated using
<code>sb-alien:make-alien</code>.
</p>
</li><li> The foreign type specifier <code>(sb-alien:struct <var>name</var> &amp;rest
<var>fields</var>)</code> describes a structure type with the specified
<var>name</var> and <var>fields</var>. Fields are allocated at the same offsets
used by the implementation&rsquo;s C compiler, as guessed by the SBCL
internals. An optional <code>:alignment</code> keyword argument can be
specified for each field to explicitly control the alignment of a
field. If <var>name</var> is <code>nil</code> then the structure is anonymous.

<p>If a named foreign <code>struct</code> specifier is passed to
<code>define-alien-type</code> or <code>with-alien</code>, then this defines,
respectively, a new global or local foreign structure type.  If no
<var>fields</var> are specified, then the fields are taken
from the current (local or global) alien structure type definition of
<var>name</var>.
</p>
</li><li> The foreign type specifier <code>(sb-alien:union <var>name</var> &amp;rest
<var>fields</var>)</code> is similar to <code>sb-alien:struct</code>, 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.

</li><li> The foreign type specifier <code>(sb-alien:enum <var>name</var> &amp;rest
<var>specs</var>)</code> describes an enumeration type that maps between integer
values and symbols. If <var>name</var> is <code>nil</code>, then the type is
anonymous.  Each element of the <var>specs</var> list is either a Lisp
symbol, or a list <code>(<var>symbol</var> <var>value</var>)</code>.  <var>value</var> is
an integer. If <var>value</var> 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).

</li><li> The foreign type specifier <code>(sb-alien:signed &amp;optional
<var>bits</var>)</code> specifies a signed integer with the specified number of
<var>bits</var> precision. The upper limit on integer
precision is determined by the machine&rsquo;s word size. If
<var>bits</var> is not specified, the maximum size will be
used.

</li><li> The foreign type specifier <code>(integer &amp;optional <var>bits</var>)</code>
is equivalent to the corresponding type specifier using
<code>sb-alien:signed</code> instead of <code>integer</code>.

</li><li> The foreign type specifier <code>(sb-alien:unsigned &amp;optional
<var>bits</var>)</code> is like corresponding type specifier using
<code>sb-alien:signed</code> except that the variable is treated as an
unsigned integer.

</li><li> The foreign type specifier <code>(boolean &amp;optional <var>bits</var>)</code> is
similar to an enumeration type, but maps from Lisp <code>nil</code> and
<code>t</code> to C <code>0</code> and <code>1</code> respectively. <var>bits</var>
determines the amount of storage allocated to hold the truth value.

</li><li> The foreign type specifier <code>single-float</code> describes a
floating-point number in IEEE single-precision format.

</li><li> The foreign type specifier <code>double-float</code> describes a
floating-point number in IEEE double-precision format.

</li><li> The foreign type specifier <code>(function <var>result-type</var> &amp;rest
<var>arg-types</var>)</code> describes a foreign function that takes arguments of
the specified <var>arg-types</var> and returns a result of type
<var>result-type</var>.  Note that the only context where a foreign
<code>function</code> type is directly specified is in the argument to
<code>sb-alien:alien-funcall</code>.  In all other contexts, foreign
functions are represented by foreign function pointer types: <code>(*
(function &hellip;))</code>.

</li><li> The foreign type specifier <code>sb-alien:system-area-pointer</code>
describes a pointer which is represented in Lisp as a
<code>system-area-pointer</code> object.  SBCL exports this type from
<code>sb-alien</code> 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&rsquo;t seem to be required by user code.

</li><li> The foreign type specifier <code>sb-alien:void</code> is used in function
types to declare that no useful value is returned.  Using
<code>alien-funcall</code> to call a <code>void</code> foreign function will
return zero values.

</li><li> <a name="index-External-formats"></a>
The foreign type specifier <code>(sb-alien:c-string &amp;key
external-format element-type not-null)</code> is similar to
<code>(* char)</code>, but is interpreted as a null-terminated string, and
is automatically converted into a Lisp string when accessed; or if the
pointer is C <code>NULL</code> or <code>0</code>, then accessing it gives Lisp
<code>nil</code> unless <code>not-null</code> is true, in which case a type-error
is signalled.

<p>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 <code>external-format</code>, 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
<code>ebcdic</code> octet representation.
</p>
<div class="lisp">
<pre class="lisp">(define-alien-routine test int (str (c-string :external-format :ebcdic-us)))
</pre></div>

<p>Lisp strings of type <code>base-string</code> 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
<code>external-format</code> and <code>element-type</code> of the <code>c-string</code>
type are compatible with the internal representation of the string. For
an SBCL built with Unicode support that means an <code>external-format</code>
of <code>:ascii</code> and an <code>element-type</code> of <code>base-char</code>. Without
Unicode support the <code>external-format</code> can also be
<code>:iso-8859-1</code>, and the <code>element-type</code> can also be
<code>character</code>. If the <code>external-format</code> or <code>element-type</code>
is not compatible, or the string is a <code>(simple-array character
(*))</code>, this data is copied by the implementation as required.
</p>
<p>Assigning a Lisp string to a <code>c-string</code> 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 <code>(*
char)</code> is assigned to a <code>c-string</code>, then the
<code>c-string</code> pointer is assigned to.  This allows
<code>c-string</code> pointers to be initialized.  For example:
</p>
<div class="lisp">
<pre class="lisp">(cl:in-package &quot;CL-USER&quot;) ; which USEs package &quot;SB-ALIEN&quot;

(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))
</pre></div>

<p>Storing Lisp <code>NIL</code> in a <code>c-string</code> writes C <code>NULL</code> to
the variable.
</p>
</li><li> <code>sb-alien</code> also exports translations of these C type
specifiers as foreign type specifiers:
<code>char</code>,
<code>short</code>,
<code>int</code>,
<code>long</code>,
<code>unsigned-char</code>,
<code>unsigned-short</code>,
<code>unsigned-int</code>,
<code>unsigned-long</code>,
<code>float</code>, <code>double</code>,
<code>size-t</code>, and <code>off-t</code>.

</li></ul>

<hr>
<a name="Operations-On-Foreign-Values"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Variables" accesskey="n" rel="next">Foreign Variables</a>, Previous: <a href="#Foreign-Types" accesskey="p" rel="prev">Foreign Types</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Operations-On-Foreign-Values-1"></a>
<h3 class="section">8.3 Operations On Foreign Values</h3>

<p>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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Accessing-Foreign-Values" accesskey="1">Accessing Foreign Values</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Coercing-Foreign-Values" accesskey="2">Coercing Foreign Values</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-Dynamic-Allocation" accesskey="3">Foreign Dynamic Allocation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Accessing-Foreign-Values"></a>
<div class="header">
<p>
Next: <a href="#Coercing-Foreign-Values" accesskey="n" rel="next">Coercing Foreign Values</a>, Up: <a href="#Operations-On-Foreign-Values" accesskey="u" rel="up">Operations On Foreign Values</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Accessing-Foreign-Values-1"></a>
<h4 class="subsection">8.3.1 Accessing Foreign Values</h4>

<dl>
<dt><a name="index-deref"></a>Function: <strong>deref</strong> <em>[sb-alien] <var>pointer-or-array</var> &amp;rest <var>indices</var></em></dt>
<dd>
<p>The <code>sb-alien:deref</code> 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. <code>deref</code> can be set with <code>setf</code> to assign a new
value.
</p></dd></dl>

<dl>
<dt><a name="index-slot"></a>Function: <strong>slot</strong> <em>[sb-alien] <var>struct-or-union</var> <var>slot-name</var></em></dt>
<dd>
<p>The <code>sb-alien:slot</code> function extracts the value of the slot named
<var>slot-name</var> from a foreign <code>struct</code> or <code>union</code>. If
<var>struct-or-union</var> is a pointer to a structure or union, then it is
automatically dereferenced.  <code>sb-alien:slot</code> can be set with
<code>setf</code> to assign a new value. Note that <var>slot-name</var> is
evaluated, and need not be a compile-time constant (but only constant
slot accesses are efficiently compiled).
</p></dd></dl>


<a name="Untyped-memory"></a>
<h4 class="subsubsection">8.3.1.1 Untyped memory</h4>

<p>As noted at the beginning of the chapter, the System Area Pointer
facilities allow untyped access to foreign memory.  <acronym>SAP</acronym>s can
be converted to and from the usual typed foreign values using
<code>sap-alien</code> and <code>alien-sap</code> (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
<acronym>SAP</acronym>s is trivial.
</p>
<dl>
<dt><a name="index-int_002dsap"></a>Function: <strong>int-sap</strong> <em>[sb-sys] <var>machine-address</var></em></dt>
<dd>
<p>Creates a <acronym>SAP</acronym> pointing at the virtual address
<var>machine-address</var>.
</p></dd></dl>

<dl>
<dt><a name="index-sap_002dref_002d32"></a>Function: <strong>sap-ref-32</strong> <em>[sb-sys] <var>sap</var> <var>offset</var></em></dt>
<dd>
<p>Access the value of the memory location at <var>offset</var> bytes from
<var>sap</var>.  This form may also be used with <code>setf</code> to alter the
memory at that location.
</p></dd></dl>

<dl>
<dt><a name="index-sap_003d"></a>Function: <strong>sap=</strong> <em>[sb-sys] <var>sap1</var> <var>sap2</var></em></dt>
<dd>
<p>Compare <var>sap1</var> and <var>sap2</var> for equality.
</p></dd></dl>

<p>Similarly named functions exist for accessing other sizes of word,
other comparisons, and other conversions.  The reader is invited to
use <code>apropos</code> and <code>describe</code> for more details
</p>
<div class="lisp">
<pre class="lisp">(apropos &quot;sap&quot; :sb-sys)
</pre></div>


<hr>
<a name="Coercing-Foreign-Values"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Dynamic-Allocation" accesskey="n" rel="next">Foreign Dynamic Allocation</a>, Previous: <a href="#Accessing-Foreign-Values" accesskey="p" rel="prev">Accessing Foreign Values</a>, Up: <a href="#Operations-On-Foreign-Values" accesskey="u" rel="up">Operations On Foreign Values</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Coercing-Foreign-Values-1"></a>
<h4 class="subsection">8.3.2 Coercing Foreign Values</h4>

<dl>
<dt><a name="index-addr"></a>Macro: <strong>addr</strong> <em>[sb-alien] <var>alien-expr</var></em></dt>
<dd>
<p>The <code>sb-alien:addr</code> macro returns a pointer to the location
specified by <var>alien-expr</var>, which must be either a foreign
variable, a use of <code>sb-alien:deref</code>, a use of
<code>sb-alien:slot</code>, or a use of <code>sb-alien:extern-alien</code>.
</p></dd></dl>

<dl>
<dt><a name="index-cast"></a>Macro: <strong>cast</strong> <em>[sb-alien] <var>foreign-value</var> <var>new-type</var></em></dt>
<dd>
<p>The <code>sb-alien:cast</code> macro converts <var>foreign-value</var> to a new
foreign value with the specified <var>new-type</var>. Both types, old and
new, must be foreign pointer, array or function types.  Note that the
resulting Lisp foreign variable object is not <code>eq</code> to the
argument, but it does refer to the same foreign data bits.
</p></dd></dl>

<dl>
<dt><a name="index-sap_002dalien"></a>Macro: <strong>sap-alien</strong> <em>[sb-alien] <var>sap</var> <var>type</var></em></dt>
<dd>
<p>The <code>sb-alien:sap-alien</code> macro converts <var>sap</var> (a system
area pointer) to a foreign value with the specified
<var>type</var>. <var>type</var> is not evaluated.
</p>
<p>The <var>type</var> must be some foreign pointer, array, or record type.
</p></dd></dl>

<dl>
<dt><a name="index-alien_002dsap"></a>Function: <strong>alien-sap</strong> <em>[sb-alien] <var>foreign-value</var></em></dt>
<dd>
<p>The <code>sb-alien:alien-sap</code> function returns the <acronym>SAP</acronym> which
points to <var>alien-value</var>&rsquo;s data.
</p>
<p>The <var>foreign-value</var> must be of some foreign pointer, array, or
record type.
</p></dd></dl>


<hr>
<a name="Foreign-Dynamic-Allocation"></a>
<div class="header">
<p>
Previous: <a href="#Coercing-Foreign-Values" accesskey="p" rel="prev">Coercing Foreign Values</a>, Up: <a href="#Operations-On-Foreign-Values" accesskey="u" rel="up">Operations On Foreign Values</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Dynamic-Allocation-1"></a>
<h4 class="subsection">8.3.3 Foreign Dynamic Allocation</h4>

<p>Lisp code can call the C standard library functions <code>malloc</code> and
<code>free</code> to dynamically allocate and deallocate foreign variables.
The Lisp code shares the same allocator with foreign C code, so it&rsquo;s
OK for foreign code to call <code>free</code> on the result of Lisp
<code>sb-alien:make-alien</code>, or for Lisp code to call
<code>sb-alien:free-alien</code> on foreign objects allocated by C code.
</p>
<a name="Macro-sb_002dalien_003amake_002dalien"></a><dl>
<dt><a name="index-make_002dalien"></a>Macro: <strong>make-alien</strong> <em>[sb-alien] type &amp;optional size</em></dt>
<dd><p>Allocate an alien of type <code>type</code> in foreign heap, and return an alien
pointer to it. The allocated memory is not initialized, and may
contain garbage. The memory is allocated using malloc(3), so it can be
passed to foreign functions which use free(3), or released using
<code>free-alien</code>.
</p>
<p>For alien stack allocation, see macro <code>with-alien</code>.
</p>
<p>The <code>type</code> argument is not evaluated. If <code>size</code> is supplied, how it is
interpreted depends on <code>type:</code>
</p>
<ul>
<li> When <code>type</code> is a foreign array type, an array of that type is
    allocated, and a pointer to it is returned. Note that you
    must use <code>deref</code> to first access the array through the pointer.

<p>If supplied, <code>size</code> is used as the first dimension for the array.
</p>
</li><li> When <code>type</code> 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 <code>(* int)</code>.

<p>If <code>size</code> is specified, then a block of that many objects is
    allocated, with the result pointing to the first one.
</p>
</li></ul>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">  (defvar *foo* (make-alien (array char 10)))
  (type-of *foo*)                 ; =&gt; (alien (* (array (signed 8) 10)))
  (setf (deref (deref foo) 0) 10) ; =&gt; 10

  (make-alien char 12)            ; =&gt; (alien (* (signed 8)))
</pre></div>
</dd></dl>
<a name="Function-sb_002dalien_003amake_002dalien_002dstring"></a><dl>
<dt><a name="index-make_002dalien_002dstring"></a>Function: <strong>make-alien-string</strong> <em>[sb-alien] string &amp;rest rest &amp;key start end external-format null-terminate</em></dt>
<dd><p>Copy part of <code>string</code> delimited by <code>start</code> and <code>end</code> into freshly
allocated foreign memory, freeable using free(3) or <code>free-alien</code>.
Returns the allocated string as a <code>(* char) </code>alien, and the number of
bytes allocated as secondary value.
</p>
<p>The string is encoded using <code>external-format</code>. If <code>null-terminate</code> is
true (the default), the alien string is terminated by an additional
null byte.
</p></dd></dl>
<a name="Function-sb_002dalien_003afree_002dalien"></a><dl>
<dt><a name="index-free_002dalien"></a>Function: <strong>free-alien</strong> <em>[sb-alien] alien</em></dt>
<dd><p>Dispose of the storage pointed to by <code>alien</code>. The <code>alien</code> must have been
allocated by <code>make-alien</code>, <code>make-alien-string</code> or malloc(3).
</p></dd></dl>

<hr>
<a name="Foreign-Variables"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Data-Structure-Examples" accesskey="n" rel="next">Foreign Data Structure Examples</a>, Previous: <a href="#Operations-On-Foreign-Values" accesskey="p" rel="prev">Operations On Foreign Values</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Variables-1"></a>
<h3 class="section">8.4 Foreign Variables</h3>

<p>Both local (stack allocated) and external (C global) foreign variables
are supported.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Local-Foreign-Variables" accesskey="1">Local Foreign Variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#External-Foreign-Variables" accesskey="2">External Foreign Variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Local-Foreign-Variables"></a>
<div class="header">
<p>
Next: <a href="#External-Foreign-Variables" accesskey="n" rel="next">External Foreign Variables</a>, Up: <a href="#Foreign-Variables" accesskey="u" rel="up">Foreign Variables</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Local-Foreign-Variables-1"></a>
<h4 class="subsection">8.4.1 Local Foreign Variables</h4>

<dl>
<dt><a name="index-with_002dalien"></a>Macro: <strong>with-alien</strong> <em>[sb-alien] <var>var-definitions</var> &amp;body <var>body</var></em></dt>
<dd>
<p>The <code>with-alien</code> 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
<code>LET</code>-allocated Lisp variables, since the variables can&rsquo;t be
captured in closures: they live only for the dynamic extent of the
body, and referring to them outside is a gruesome error.
</p>
<p>The <var>var-definitions</var> argument is a list of
variable definitions, each of the form
</p><div class="lisp">
<pre class="lisp">(<var>name</var> <var>type</var> &amp;optional <var>initial-value</var>)
</pre></div>

<p>The names of the variables are established as symbol-macros; the
bindings have lexical scope, and may be assigned with <code>setq</code> or
<code>setf</code>.
</p>
<p>The <code>with-alien</code> macro also establishes a new scope for named
structures and unions.  Any <var>type</var> 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 <var>foo</var> can be referenced by its name
using <code>(struct <var>foo</var>)</code>.
</p></dd></dl>

<hr>
<a name="External-Foreign-Variables"></a>
<div class="header">
<p>
Previous: <a href="#Local-Foreign-Variables" accesskey="p" rel="prev">Local Foreign Variables</a>, Up: <a href="#Foreign-Variables" accesskey="u" rel="up">Foreign Variables</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="External-Foreign-Variables-1"></a>
<h4 class="subsection">8.4.2 External Foreign Variables</h4>

<p>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 <code>extern-alien</code>, <code>define-alien-variable</code> and
<code>define-alien-routine</code> use this conversion heuristic:
</p>
<ul>
<li> Alien names are converted to Lisp names by uppercasing and replacing
underscores with hyphens.

</li><li> Conversely, Lisp names are converted to alien names by lowercasing and
replacing hyphens with underscores.

</li><li> Both the Lisp symbol and alien string names may be separately
specified by using a list of the form

<div class="lisp">
<pre class="lisp">(alien-string lisp-symbol)
</pre></div>

</li></ul>

<dl>
<dt><a name="index-define_002dalien_002dvariable"></a>Macro: <strong>define-alien-variable</strong> <em>[sb-alien] <var>name</var> <var>type</var></em></dt>
<dd>
<p>The <code>define-alien-variable</code> macro defines <var>name</var> as an
external foreign variable of the specified foreign <code>type</code>.
<var>name</var> and <code>type</code> are not evaluated.  The Lisp name of the
variable (see above) becomes a global alien variable.  Global alien
variables are effectively &ldquo;global symbol macros&rdquo;; a reference to the
variable fetches the contents of the external variable.  Similarly,
setting the variable stores new contents &ndash; the new contents must be
of the declared <code>type</code>. Someday, they may well be implemented
using the <acronym>ANSI</acronym> <code>define-symbol-macro</code> mechanism, but as
of SBCL 0.7.5, they are still implemented using an older more-or-less
parallel mechanism inherited from CMUCL.
</p>
<p>For example, to access a C-level counter <var>foo</var>, one could write
</p>
<div class="lisp">
<pre class="lisp">(define-alien-variable &quot;foo&quot; 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)
</pre></div>
</dd></dl>

<dl>
<dt><a name="index-get_002derrno"></a>Function: <strong>get-errno</strong> <em>[sb-alien]</em></dt>
<dd>
<p>Since in modern C libraries, the <code>errno</code> &ldquo;variable&rdquo; 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
<code>define-alien-variable</code> mechanism. Instead, SBCL provides
the operator <code>sb-alien:get-errno</code> to allow Lisp code to read it.
</p></dd></dl>

<dl>
<dt><a name="index-extern_002dalien"></a>Macro: <strong>extern-alien</strong> <em>[sb-alien] <var>name</var> <var>type</var></em></dt>
<dd>
<p>The <code>extern-alien</code> macro returns an alien with the specified
<var>type</var> which points to an externally defined value.  <var>name</var> is
not evaluated, and may be either a string or a symbol.  <var>type</var> is
an unevaluated alien type specifier.
</p></dd></dl>

<hr>
<a name="Foreign-Data-Structure-Examples"></a>
<div class="header">
<p>
Next: <a href="#Loading-Shared-Object-Files" accesskey="n" rel="next">Loading Shared Object Files</a>, Previous: <a href="#Foreign-Variables" accesskey="p" rel="prev">Foreign Variables</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Data-Structure-Examples-1"></a>
<h3 class="section">8.5 Foreign Data Structure Examples</h3>

<p>Now that we have alien types, operations and variables, we can
manipulate foreign data structures.  This C declaration
</p>
<div class="example">
<pre class="example">struct foo {
    int a;
    struct foo *b[100];
};
</pre></div>

<p>can be translated into the following alien type:
</p>
<div class="lisp">
<pre class="lisp">(define-alien-type nil
  (struct foo
    (a int)
    (b (array (* (struct foo)) 100))))
</pre></div>

<p>Once the <code>foo</code> alien type has been defined as above, the C
expression
</p>
<div class="example">
<pre class="example">struct foo f;
f.b[7].a;
</pre></div>

<p>can be translated in this way:
</p>
<div class="lisp">
<pre class="lisp">(with-alien ((f (struct foo)))
  (slot (deref (slot f 'b) 7) 'a)
  ;;
  ;; Do something with f...
  )
</pre></div>

<p>Or consider this example of an external C variable and some accesses:
</p>
<div class="example">
<pre class="example">struct c_struct {
        short x, y;
        char a, b;
        int z;
        c_struct *n;
};
extern struct c_struct *my_struct;
my_struct-&gt;x++;
my_struct-&gt;a = 5;
my_struct = my_struct-&gt;n;
</pre></div>

<p>which can be manipulated in Lisp like this:
</p>
<div class="lisp">
<pre class="lisp">(define-alien-type nil
  (struct c-struct
          (x short)
          (y short)
          (a char)
          (b char)
          (z int)
          (n (* c-struct))))
(define-alien-variable &quot;my_struct&quot; (* c-struct))
(incf (slot my-struct 'x))
(setf (slot my-struct 'a) 5)
(setq my-struct (slot my-struct 'n))
</pre></div>

<hr>
<a name="Loading-Shared-Object-Files"></a>
<div class="header">
<p>
Next: <a href="#Foreign-Function-Calls" accesskey="n" rel="next">Foreign Function Calls</a>, Previous: <a href="#Foreign-Data-Structure-Examples" accesskey="p" rel="prev">Foreign Data Structure Examples</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Loading-Shared-Object-Files-1"></a>
<h3 class="section">8.6 Loading Shared Object Files</h3>

<p>Foreign object files can be loaded into the running Lisp process by
calling <code>load-shared-object</code>.
</p>
<a name="Function-sb_002dalien_003aload_002dshared_002dobject"></a><dl>
<dt><a name="index-load_002dshared_002dobject"></a>Function: <strong>load-shared-object</strong> <em>[sb-alien] pathname &amp;key dont-save</em></dt>
<dd><p>Load a shared library / dynamic shared object file / similar foreign
container specified by designated <code>pathname</code>, such as a .so on an <code>elf</code> platform.
</p>
<p>Locating the shared object follows standard rules of the platform, consult the
manual page for dlopen(3) for details. Typically paths specified by
environment variables such as LD_LIBRARY_PATH are searched if the <code>pathname</code> has
no directory, but on some systems (eg. Mac <code>os</code> X) search may happen even if
<code>pathname</code> is absolute. (On Windows LoadLibrary is used instead of dlopen(3).)
</p>
<p>On non-Windows platforms calling <code>load-shared-object</code> again with a <code>pathname</code>
<code>equal</code> to the designated pathname of a previous call will replace the old
definitions; if a symbol was previously referenced through 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.
</p>
<p><code>load-shared-object</code> interacts with <code>sb-ext:save-lisp-and-die:</code>
</p>
<p>1. If <code>dont-save</code> is true (default is NIL), the shared object will be dropped
when <code>save-lisp-and-die</code> is called <code>--</code> otherwise shared objects are reloaded
automatically when a saved core starts up. Specifying <code>dont-save</code> can be useful
when the location of the shared object on startup is uncertain.
</p>
<p>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
<code>save-lisp-and-die</code>. On those platforms where this is not supported, a <code>warning</code>
will be signalled when the core is saved <code>--</code> this is orthogonal from <code>dont-save</code>.
</p></dd></dl>

<a name="Function-sb_002dalien_003aunload_002dshared_002dobject"></a><dl>
<dt><a name="index-unload_002dshared_002dobject"></a>Function: <strong>unload-shared-object</strong> <em>[sb-alien] pathname</em></dt>
<dd><p>Unloads the shared object loaded earlier using the designated <code>pathname</code> with
<code>load-shared-object</code>, to the degree supported on the platform.
</p>
<p>Experimental.
</p></dd></dl>

<hr>
<a name="Foreign-Function-Calls"></a>
<div class="header">
<p>
Next: <a href="#Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface" accesskey="n" rel="next">Step-By-Step Example of the Foreign Function Interface</a>, Previous: <a href="#Loading-Shared-Object-Files" accesskey="p" rel="prev">Loading Shared Object Files</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-Function-Calls-1"></a>
<h3 class="section">8.7 Foreign Function Calls</h3>

<p>The foreign function call interface allows a Lisp program to call
many functions written in languages that use the C calling convention.
</p>
<p>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
<code>:sb-thread</code> feature should also read the section about threads,
<a href="#Threading">Threading</a>.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#The-alien_002dfuncall-Primitive" accesskey="1">The alien-funcall Primitive</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#The-define_002dalien_002droutine-Macro" accesskey="2">The define-alien-routine Macro</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#define_002dalien_002droutine-Example" accesskey="3">define-alien-routine Example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Calling-Lisp-From-C" accesskey="4">Calling Lisp From C</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="The-alien_002dfuncall-Primitive"></a>
<div class="header">
<p>
Next: <a href="#The-define_002dalien_002droutine-Macro" accesskey="n" rel="next">The define-alien-routine Macro</a>, Up: <a href="#Foreign-Function-Calls" accesskey="u" rel="up">Foreign Function Calls</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-alien_002dfuncall-Primitive-1"></a>
<h4 class="subsection">8.7.1 The <code>alien-funcall</code> Primitive</h4>

<dl>
<dt><a name="index-alien_002dfuncall"></a>Function: <strong>alien-funcall</strong> <em>[sb-alien] <var>alien-function</var> &amp;rest <var>arguments</var></em></dt>
<dd>
<p>The <code>alien-funcall</code> function is the foreign function call
primitive: <var>alien-function</var> is called with the supplied
<var>arguments</var> and its C return value is returned as a Lisp value.
The <var>alien-function</var> is an arbitrary run-time expression; to refer
to a constant function, use <code>extern-alien</code> or a value defined by
<code>define-alien-routine</code>.
</p>
<p>The type of <code>alien-function</code> must be <code>(alien (function
...))</code>  or <code>(alien (* (function ...)))</code>.  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:
</p>
<ul>
<li> Structure type return values are not implemented.

</li><li> Passing of structures by value is not implemented.

</li></ul>

</dd></dl>

<p>Here is an example which allocates a <code>(struct foo)</code>, calls a
foreign function to initialize it, then returns a Lisp vector of all
the <code>(* (struct foo))</code> objects filled in by the foreign call:
</p>
<div class="lisp">
<pre class="lisp">;; Allocate a foo on the stack.
(with-alien ((f (struct foo)))
  ;; Call some C function to fill in foo fields.
  (alien-funcall (extern-alien &quot;mangle_foo&quot; (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)))
</pre></div>

<hr>
<a name="The-define_002dalien_002droutine-Macro"></a>
<div class="header">
<p>
Next: <a href="#define_002dalien_002droutine-Example" accesskey="n" rel="next">define-alien-routine Example</a>, Previous: <a href="#The-alien_002dfuncall-Primitive" accesskey="p" rel="prev">The alien-funcall Primitive</a>, Up: <a href="#Foreign-Function-Calls" accesskey="u" rel="up">Foreign Function Calls</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-define_002dalien_002droutine-Macro-1"></a>
<h4 class="subsection">8.7.2 The <code>define-alien-routine</code> Macro</h4>

<dl>
<dt><a name="index-define_002dalien_002droutine"></a>Macro: <strong>define-alien-routine</strong> <em>[sb-alien] <var>name</var> <var>result-type</var> &amp;rest <var>arg-specifiers</var></em></dt>
<dd>
<p>The <code>define-alien-routine</code> 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.
</p>
<p><var>name</var> 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
<code>extern-alien</code>.  <var>result-type</var> is the alien type of the
return value.
</p>
<p>Each element of the <var>arg-specifiers</var> list
specifies an argument to the foreign function, and is
of the form
</p><div class="lisp">
<pre class="lisp">(aname atype &amp;amp;optional style)
</pre></div>

<p><var>aname</var> is the symbol name of the argument to the constructed
function (for documentation). <var>atype</var> is the alien type of
corresponding foreign argument.  The semantics of the actual call are
the same as for <code>alien-funcall</code>. <var>style</var> specifies how this
argument should be handled at call and return time, and should be one
of the following:
</p>
<ul>
<li> <code>:in</code> specifies that the argument is passed by value. This is the
default. <code>:in</code> arguments have no corresponding return value from
the Lisp function.

</li><li> <code>:copy</code> is similar to <code>:in</code>, but the argument is copied to a
pre-allocated object and a pointer to this object is passed to the
foreign routine.

</li><li> <code>:out</code> 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).  <code>:out</code> and <code>:in-out</code> 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).

</li><li> <code>:in-out</code> is a combination of <code>:copy</code> and <code>:out</code>.  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.

</li></ul>

<blockquote>
<p>Note: Any efficiency-critical foreign interface function should be inline
expanded, which can be done by preceding the
<code>define-alien-routine</code> call with:
</p>
<div class="lisp">
<pre class="lisp">(declaim (inline lisp-name))
</pre></div>

<p>In addition to avoiding the Lisp call overhead, this allows
pointers, word-integers and floats to be passed using non-descriptor
representations, avoiding consing.)
</p></blockquote>

</dd></dl>

<hr>
<a name="define_002dalien_002droutine-Example"></a>
<div class="header">
<p>
Next: <a href="#Calling-Lisp-From-C" accesskey="n" rel="next">Calling Lisp From C</a>, Previous: <a href="#The-define_002dalien_002droutine-Macro" accesskey="p" rel="prev">The define-alien-routine Macro</a>, Up: <a href="#Foreign-Function-Calls" accesskey="u" rel="up">Foreign Function Calls</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="define_002dalien_002droutine-Example-1"></a>
<h4 class="subsection">8.7.3 <code>define-alien-routine</code> Example</h4>

<p>Consider the C function <code>cfoo</code> with the following calling
convention:
</p>
<div class="example">
<pre class="example">void
cfoo (str, a, i)
    char *str;
    char *a; /* update */
    int *i; /* out */
{
  /* body of cfoo(...) */
}
</pre></div>

<p>This can be described by the following call to
<code>define-alien-routine</code>:
</p>
<div class="lisp">
<pre class="lisp">(define-alien-routine &quot;cfoo&quot; void
  (str c-string)
  (a char :in-out)
  (i int :out))
</pre></div>

<p>The Lisp function <code>cfoo</code> will have two arguments (<var>str</var> and
<var>a</var>) and two return values (<var>a</var> and <var>i</var>).
</p>
<hr>
<a name="Calling-Lisp-From-C"></a>
<div class="header">
<p>
Previous: <a href="#define_002dalien_002droutine-Example" accesskey="p" rel="prev">define-alien-routine Example</a>, Up: <a href="#Foreign-Function-Calls" accesskey="u" rel="up">Foreign Function Calls</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Calling-Lisp-From-C-1"></a>
<h4 class="subsection">8.7.4 Calling Lisp From C</h4>

<p>Calling Lisp functions from C is sometimes possible, but is extremely
hackish and poorly supported as of SBCL 0.7.5.  See <code>funcall0</code>
&hellip; <code>funcall3</code> 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
<samp>INTERNALS</samp> documentation.
</p>
<p>Note that the garbage collector moves objects, and won&rsquo;t be
able to fix up any references in C variables.  There are three
mechanisms for coping with this:
</p>
<ol>
<li> The <code>sb-ext:purify</code> 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

</li><li> <code>sb-sys:with-pinned-objects</code> 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).

</li><li> Disable GC, using the <code>without-gcing</code> macro.
</li></ol>






<hr>
<a name="Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface"></a>
<div class="header">
<p>
Previous: <a href="#Foreign-Function-Calls" accesskey="p" rel="prev">Foreign Function Calls</a>, Up: <a href="#Foreign-Function-Interface" accesskey="u" rel="up">Foreign Function Interface</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Step_002dBy_002dStep-Example-of-the-Foreign-Function-Interface-1"></a>
<h3 class="section">8.8 Step-By-Step Example of the Foreign Function Interface</h3>

<p>This section presents a complete example of an interface to a somewhat
complicated C function.
</p>
<p>Suppose you have the following C function which you want to be able to
call from Lisp in the file <samp>test.c</samp>
</p>
<div class="example">
<pre class="example">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(&quot;i = %d\n&quot;, i);
  printf(&quot;s = %s\n&quot;, s);
  printf(&quot;r-&gt;x = %d\n&quot;, r-&gt;x);
  printf(&quot;r-&gt;s = %s\n&quot;, r-&gt;s);
  for (j = 0; j &lt; 10; j++) printf(&quot;a[%d] = %d.\n&quot;, j, a[j]);
  r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
  r2-&gt;x = i + 5;
  r2-&gt;s = &quot;a C string&quot;;
  return(r2);
};
</pre></div>

<p>It is possible to call this C function from Lisp using the file
<samp>test.lisp</samp> containing
</p>
<div class="lisp">
<pre class="lisp">(cl:defpackage &quot;TEST-C-CALL&quot; (:use &quot;CL&quot; &quot;SB-ALIEN&quot; &quot;SB-C-CALL&quot;))
(cl:in-package &quot;TEST-C-CALL&quot;)

;;; 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) &quot;a Lisp string&quot;)

    (with-alien ((res (* (struct c-struct))
                      (c-function 5 &quot;another Lisp string&quot; (addr c-struct) ar)))
      (format t &quot;~&amp;amp;back from C function~%&quot;)
      (multiple-value-prog1
          (values (slot res 'x)
                  (slot res 's))

        ;; Deallocate result. (after we are done referring to it:
        ;; &quot;Pillage, *then* burn.&quot;)
        (free-alien res)))))
</pre></div>

<p>To execute the above example, it is necessary to compile the C
routine, e.g.: &lsquo;<samp>cc -c test.c &amp;&amp; ld -shared -o test.so test.o</samp>&rsquo; (In
order to enable incremental loading with some linkers, you may need to
say &lsquo;<samp>cc -G 0 -c test.c</samp>&rsquo;)
</p>
<p>Once the C code has been compiled, you can start up Lisp and load it in:
&lsquo;<samp>sbcl</samp>&rsquo;.  Lisp should start up with its normal prompt.
</p>
<p>Within Lisp, compile the Lisp file. (This step can be done
separately. You don&rsquo;t have to recompile every time.)
&lsquo;<samp>(compile-file &quot;test.lisp&quot;)</samp>&rsquo;
</p>
<p>Within Lisp, load the foreign object file to define the necessary
symbols: &lsquo;<samp>(load-shared-object &quot;test.so&quot;)</samp>&rsquo;.
</p>
<p>Now you can load the compiled Lisp (&ldquo;fasl&rdquo;) file into Lisp:
&lsquo;<samp>(load &quot;test.fasl&quot;)</samp>&rsquo;
And once the Lisp file is loaded, you can call the
Lisp routine that sets up the parameters and calls the C
function:
&lsquo;<samp>(test-c-call::call-cfun)</samp>&rsquo;
</p>
<p>The C routine should print the following information to standard output:
</p>
<div class="example">
<pre class="example">i = 5
s = another Lisp string
r-&gt;x = 20
r-&gt;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.
</pre></div>

<p>After return from the C function,
the Lisp wrapper function should print the following output:
</p>
<div class="example">
<pre class="example">back from C function
</pre></div>

<p>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:
</p>
<div class="example">
<pre class="example">10
&quot;a C string&quot;
</pre></div>
<hr>
<a name="Pathnames"></a>
<div class="header">
<p>
Next: <a href="#Streams" accesskey="n" rel="next">Streams</a>, Previous: <a href="#Foreign-Function-Interface" accesskey="p" rel="prev">Foreign Function Interface</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Pathnames-1"></a>
<h2 class="chapter">9 Pathnames</h2>

<a name="index-Pathnames"></a>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Lisp-Pathnames" accesskey="1">Lisp Pathnames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Native-Filenames" accesskey="2">Native Filenames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Lisp-Pathnames"></a>
<div class="header">
<p>
Next: <a href="#Native-Filenames" accesskey="n" rel="next">Native Filenames</a>, Up: <a href="#Pathnames" accesskey="u" rel="up">Pathnames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Lisp-Pathnames-1"></a>
<h3 class="section">9.1 Lisp Pathnames</h3>

<p>There are many aspects of ANSI Common Lisp&rsquo;s pathname support which are
implementation-defined and so need documentation.
</p>

<a name="Home-Directory-Specifiers"></a>
<h4 class="subsection">9.1.1 Home Directory Specifiers</h4>

<p>SBCL accepts the keyword <code>:home</code> and a list of the form
<code>(:home &quot;username&quot;)</code> as a directory component immediately
following <code>:absolute</code>.
</p>
<p><code>:home</code> is represented in namestrings by <code>~/</code> and
<code>(:home &quot;username&quot;</code> by <code>~username/</code> at the start of the
namestring. Tilde-characters elsewhere in namestrings represent
themselves.
</p>
<p>Home directory specifiers are resolved to home directory of the
current or specified user by <code>native-namestring</code>, which is used
by the implementation to translate pathnames before passing them on to
operating system specific routines.
</p>
<p>Using <code>(:home &quot;user&quot;)</code> form on Windows signals an error.
</p>
<a name="The-SYS-Logical-Pathname-Host"></a>
<h4 class="subsection">9.1.2 The SYS Logical Pathname Host</h4>

<a name="index-Logical-pathnames"></a>
<a name="index-Pathnames_002c-logical"></a>
<a name="index-logical_002dpathname_002dtranslations-_005bcl_005d"></a>
<a name="index-_0028setf-logical_002dpathname_002dtranslations-_005bcl_005d_0029"></a>


<p>The logical pathname host named by <code>&quot;SYS&quot;</code> exists in SBCL.  Its
<code>logical-pathname-translations</code> may be set by the site or the user
applicable to point to the locations of the system&rsquo;s sources; in
particular, the core system&rsquo;s source files match the logical pathname
<code>&quot;SYS:SRC;**;*.*.*&quot;</code>, and the contributed modules&rsquo; source files
match <code>&quot;SYS:CONTRIB;**;*.*.*&quot;</code>.
</p>
<a name="Function-sb_002dext_003aset_002dsbcl_002dsource_002dlocation"></a><dl>
<dt><a name="index-set_002dsbcl_002dsource_002dlocation"></a>Function: <strong>set-sbcl-source-location</strong> <em>[sb-ext] pathname</em></dt>
<dd><p>Initialize the <code>sys</code> logical host based on <code>pathname</code>, which should be
the top-level directory of the <code>sbcl</code> sources. This will replace any
existing translations for &quot;SYS:SRC;&quot;, &quot;SYS:CONTRIB;&quot;, and
&quot;SYS:OUTPUT;&quot;. Other &quot;SYS:&quot; translations are preserved.
</p></dd></dl>

<hr>
<a name="Native-Filenames"></a>
<div class="header">
<p>
Previous: <a href="#Lisp-Pathnames" accesskey="p" rel="prev">Lisp Pathnames</a>, Up: <a href="#Pathnames" accesskey="u" rel="up">Pathnames</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Native-Filenames-1"></a>
<h3 class="section">9.2 Native Filenames</h3>

<p>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.
</p>
<p>To allow the user to deal with this, the following functions are
provided: <code>parse-native-namestring</code> and <code>native-pathname</code>
return the closest equivalent Lisp pathname to a given string
(appropriate for the Operating System), while <code>native-namestring</code>
converts a non-wild pathname designator to the equivalent native
namestring, if possible.  Some Lisp pathname concepts (such as the
<code>:back</code> directory component) have no direct equivalents in most
Operating Systems; the behaviour of <code>native-namestring</code> 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 <code>equal</code>.
</p>
<a name="Function-sb_002dext_003aparse_002dnative_002dnamestring"></a><dl>
<dt><a name="index-parse_002dnative_002dnamestring"></a>Function: <strong>parse-native-namestring</strong> <em>[sb-ext] thing &amp;optional host defaults &amp;key start end junk-allowed as-directory</em></dt>
<dd><p>Convert <code>thing</code> into a pathname, using the native conventions
appropriate for the pathname host <code>host</code>, or if not specified the
host of <code>defaults</code>.  If <code>thing</code> is a string, the parse is bounded by
<code>start</code> and <code>end</code>, and error behaviour is controlled by <code>junk-allowed</code>,
as with <code>parse-namestring</code>.  For file systems whose native
conventions allow directories to be indicated as files, if
<code>as-directory</code> is true, return a pathname denoting <code>thing</code> as a
directory.
</p></dd></dl>
<a name="Function-sb_002dext_003anative_002dpathname"></a><dl>
<dt><a name="index-native_002dpathname"></a>Function: <strong>native-pathname</strong> <em>[sb-ext] pathspec</em></dt>
<dd><p>Convert <code>pathspec</code> (a pathname designator) into a pathname, assuming
the operating system native pathname conventions.
</p></dd></dl>
<a name="Function-sb_002dext_003anative_002dnamestring"></a><dl>
<dt><a name="index-native_002dnamestring"></a>Function: <strong>native-namestring</strong> <em>[sb-ext] pathname &amp;key as-file</em></dt>
<dd><p>Construct the full native (name)string form of <code>pathname</code>.  For
file systems whose native conventions allow directories to be
indicated as files, if <code>as-file</code> is true and the name, type, and
version components of <code>pathname</code> are all <code>nil</code> or <code>:unspecific</code>,
construct a string that names the directory according to the file
system&rsquo;s syntax for files.
</p></dd></dl>

<p>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 &ldquo;as a directory name&rdquo; or to produce a native file
name that names a directory &ldquo;as a file&rdquo;.  For these cases,
<code>parse-native-namestring</code> accepts the keyword argument
<code>as-directory</code> to force a filename to parse as a directory, and
<code>native-namestring</code> accepts the keyword argument <code>as-file</code>
to force a pathname to unparse as a file.  For example,
</p>
<div class="lisp">
<pre class="lisp">; On Unix, the directory &quot;/tmp/&quot; can be denoted by &quot;/tmp/&quot; or &quot;/tmp&quot;.
; Under the default rules for native filenames, these parse and
; unparse differently.
(defvar *p*)
(setf *p* (parse-native-namestring &quot;/tmp/&quot;)) &rArr; #P&quot;/tmp/&quot;
(pathname-name *p*) &rArr; NIL
(pathname-directory *p*) &rArr; (:ABSOLUTE &quot;tmp&quot;)
(native-namestring *p*) &rArr; &quot;/tmp/&quot;

(setf *p* (parse-native-namestring &quot;/tmp&quot;)) &rArr; #P&quot;/tmp&quot;
(pathname-name *p*) &rArr; &quot;tmp&quot;
(pathname-directory *p*) &rArr; (:ABSOLUTE)
(native-namestring *p*) &rArr; &quot;/tmp&quot;

; 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 &quot;/tmp&quot;
                                   nil *default-pathname-defaults*
                                   :as-directory t)) &rArr; #P&quot;/tmp/&quot;
(pathname-name *p*) &rArr; NIL
(pathname-directory *p*) &rArr; (:ABSOLUTE &quot;tmp&quot;)

; 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 &quot;/tmp/&quot;)) &rArr; #P&quot;/tmp/&quot;
(native-namestring *p* :as-file t) &rArr; &quot;/tmp&quot;
</pre></div>
<hr>
<a name="Streams"></a>
<div class="header">
<p>
Next: <a href="#Package-Locks" accesskey="n" rel="next">Package Locks</a>, Previous: <a href="#Pathnames" accesskey="p" rel="prev">Pathnames</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Streams-1"></a>
<h2 class="chapter">10 Streams</h2>

<p>Streams which read or write Lisp character data from or to the outside
world &ndash; files, sockets or other external entities &ndash; require the
specification of a conversion between the external, binary data and the
Lisp characters.  In ANSI Common Lisp, this is done by specifying the
<code>:external-format</code> argument when the stream is created.  The major
information required is an <em>encoding</em>, specified by a keyword
naming that encoding; however, it is also possible to specify
refinements to that encoding as additional options to the external
format designator.
</p>
<p>In addition, SBCL supports various extensions of ANSI Common Lisp
streams:
</p>
<dl compact="compact">
<dt><strong>Bivalent Streams</strong></dt>
<dd><p>A type of stream that can read and write both <code>character</code> and
<code>(unsigned-byte 8)</code> values.
</p>
</dd>
<dt><strong>Gray Streams</strong></dt>
<dd><p>User-overloadable CLOS classes whose instances can be used as Lisp
streams (e.g. passed as the first argument to <code>format</code>).
</p>
</dd>
<dt><strong>Simple Streams</strong></dt>
<dd><p>The bundled contrib module <em>sb-simple-streams</em> implements a subset
of the Franz Allegro simple-streams proposal.
</p>
</dd>
</dl>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#External-Formats" accesskey="1">External Formats</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Bivalent-Streams" accesskey="2">Bivalent Streams</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Gray-Streams" accesskey="3">Gray Streams</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Simple-Streams" accesskey="4">Simple Streams</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="External-Formats"></a>
<div class="header">
<p>
Next: <a href="#Bivalent-Streams" accesskey="n" rel="next">Bivalent Streams</a>, Up: <a href="#Streams" accesskey="u" rel="up">Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="External-Formats-1"></a>
<h3 class="section">10.1 External Formats</h3>
<a name="index-External-formats-1"></a>

<a name="index-stream_002dexternal_002dformat-_005bcl_005d"></a>
<p>The encodings supported by SBCL as external formats are named by
keyword.  Each encoding has a canonical name, which will be encoding
returned by <code>stream-external-format</code>, and a number of aliases for
convenience, as shown in the table below:
</p>
<dl compact="compact">
<dt><code>:ASCII</code></dt>
<dd><p><code>:US-ASCII</code>, <code>:ANSI_X3.4-1968</code>, <code>:ISO-646</code>, <code>:ISO-646-US</code>, <code>:|646|</code>
</p>
</dd>
<dt><code>:CP1250</code></dt>
<dd><p><code>:|cp1250|</code>, <code>:WINDOWS-1250</code>, <code>:|windows-1250|</code>
</p>
</dd>
<dt><code>:CP1251</code></dt>
<dd><p><code>:|cp1251|</code>, <code>:WINDOWS-1251</code>, <code>:|windows-1251|</code>
</p>
</dd>
<dt><code>:CP1252</code></dt>
<dd><p><code>:|cp1252|</code>, <code>:WINDOWS-1252</code>, <code>:|windows-1252|</code>
</p>
</dd>
<dt><code>:CP1253</code></dt>
<dd><p><code>:|cp1253|</code>, <code>:WINDOWS-1253</code>, <code>:|windows-1253|</code>
</p>
</dd>
<dt><code>:CP1254</code></dt>
<dd><p><code>:|cp1254|</code>
</p>
</dd>
<dt><code>:CP1255</code></dt>
<dd><p><code>:|cp1255|</code>, <code>:WINDOWS-1255</code>, <code>:|windows-1255|</code>
</p>
</dd>
<dt><code>:CP1256</code></dt>
<dd><p><code>:|cp1256|</code>, <code>:WINDOWS-1256</code>, <code>:|windows-1256|</code>
</p>
</dd>
<dt><code>:CP1257</code></dt>
<dd><p><code>:|cp1257|</code>, <code>:WINDOWS-1257</code>, <code>:|windows-1257|</code>
</p>
</dd>
<dt><code>:CP1258</code></dt>
<dd><p><code>:|cp1258|</code>, <code>:WINDOWS-1258</code>, <code>:|windows-1258|</code>
</p>
</dd>
<dt><code>:CP437</code></dt>
<dd><p><code>:|cp437|</code>
</p>
</dd>
<dt><code>:CP850</code></dt>
<dd><p><code>:|cp850|</code>
</p>
</dd>
<dt><code>:CP852</code></dt>
<dd><p><code>:|cp852|</code>
</p>
</dd>
<dt><code>:CP855</code></dt>
<dd><p><code>:|cp855|</code>
</p>
</dd>
<dt><code>:CP857</code></dt>
<dd><p><code>:|cp857|</code>
</p>
</dd>
<dt><code>:CP860</code></dt>
<dd><p><code>:|cp860|</code>
</p>
</dd>
<dt><code>:CP861</code></dt>
<dd><p><code>:|cp861|</code>
</p>
</dd>
<dt><code>:CP862</code></dt>
<dd><p><code>:|cp862|</code>
</p>
</dd>
<dt><code>:CP863</code></dt>
<dd><p><code>:|cp863|</code>
</p>
</dd>
<dt><code>:CP864</code></dt>
<dd><p><code>:|cp864|</code>
</p>
</dd>
<dt><code>:CP865</code></dt>
<dd><p><code>:|cp865|</code>
</p>
</dd>
<dt><code>:CP866</code></dt>
<dd><p><code>:|cp866|</code>
</p>
</dd>
<dt><code>:CP869</code></dt>
<dd><p><code>:|cp869|</code>
</p>
</dd>
<dt><code>:CP874</code></dt>
<dd><p><code>:|cp874|</code>
</p>
</dd>
<dt><code>:EBCDIC-US</code></dt>
<dd><p><code>:CP037</code>, <code>:|cp037|</code>, <code>:IBM-037</code>, <code>:IBM037</code>
</p>
</dd>
<dt><code>:EUC-JP</code></dt>
<dd><p><code>:EUCJP</code>, <code>:|eucJP|</code>
</p>
</dd>
<dt><code>:GBK</code></dt>
<dd><p><code>:CP936</code>
</p>
</dd>
<dt><code>:ISO-8859-10</code></dt>
<dd><p><code>:|iso-8859-10|</code>, <code>:LATIN-6</code>, <code>:|latin-6|</code>
</p>
</dd>
<dt><code>:ISO-8859-11</code></dt>
<dd><p><code>:|iso-8859-11|</code>
</p>
</dd>
<dt><code>:ISO-8859-13</code></dt>
<dd><p><code>:|iso-8859-13|</code>, <code>:LATIN-7</code>, <code>:|latin-7|</code>
</p>
</dd>
<dt><code>:ISO-8859-14</code></dt>
<dd><p><code>:|iso-8859-14|</code>, <code>:LATIN-8</code>, <code>:|latin-8|</code>
</p>
</dd>
<dt><code>:ISO-8859-2</code></dt>
<dd><p><code>:|iso-8859-2|</code>, <code>:LATIN-2</code>, <code>:|latin-2|</code>
</p>
</dd>
<dt><code>:ISO-8859-3</code></dt>
<dd><p><code>:|iso-8859-3|</code>, <code>:LATIN-3</code>, <code>:|latin-3|</code>
</p>
</dd>
<dt><code>:ISO-8859-4</code></dt>
<dd><p><code>:|iso-8859-4|</code>, <code>:LATIN-4</code>, <code>:|latin-4|</code>
</p>
</dd>
<dt><code>:ISO-8859-5</code></dt>
<dd><p><code>:|iso-8859-5|</code>
</p>
</dd>
<dt><code>:ISO-8859-6</code></dt>
<dd><p><code>:|iso-8859-6|</code>
</p>
</dd>
<dt><code>:ISO-8859-7</code></dt>
<dd><p><code>:|iso-8859-7|</code>
</p>
</dd>
<dt><code>:ISO-8859-8</code></dt>
<dd><p><code>:|iso-8859-8|</code>
</p>
</dd>
<dt><code>:ISO-8859-9</code></dt>
<dd><p><code>:|iso-8859-9|</code>, <code>:LATIN-5</code>, <code>:|latin-5|</code>
</p>
</dd>
<dt><code>:KOI8-R</code></dt>
<dd><p><code>:|koi8-r|</code>
</p>
</dd>
<dt><code>:KOI8-U</code></dt>
<dd><p><code>:|koi8-u|</code>
</p>
</dd>
<dt><code>:LATIN-1</code></dt>
<dd><p><code>:LATIN1</code>, <code>:ISO-8859-1</code>, <code>:ISO8859-1</code>
</p>
</dd>
<dt><code>:LATIN-9</code></dt>
<dd><p><code>:LATIN9</code>, <code>:ISO-8859-15</code>, <code>:ISO8859-15</code>
</p>
</dd>
<dt><code>:MAC-ROMAN</code></dt>
<dd><p><code>:|mac-roman|</code>, <code>:|MacRoman|</code>, <code>:MAC</code>, <code>:|mac|</code>, <code>:MACINTOSH</code>, <code>:|macintosh|</code>
</p>
</dd>
<dt><code>:SHIFT_JIS</code></dt>
<dd><p><code>:SJIS</code>, <code>:|Shift_JIS|</code>, <code>:CP932</code>
</p>
</dd>
<dt><code>:UCS-2BE</code></dt>
<dd><p><code>:UCS2BE</code>
</p>
</dd>
<dt><code>:UCS-2LE</code></dt>
<dd><p><code>:UCS2LE</code>
</p>
</dd>
<dt><code>:UCS-4BE</code></dt>
<dd><p><code>:UCS4BE</code>
</p>
</dd>
<dt><code>:UCS-4LE</code></dt>
<dd><p><code>:UCS4LE</code>
</p>
</dd>
<dt><code>:UTF-16BE</code></dt>
<dd><p><code>:UTF16BE</code>
</p>
</dd>
<dt><code>:UTF-16LE</code></dt>
<dd><p><code>:UTF16LE</code>
</p>
</dd>
<dt><code>:UTF-32BE</code></dt>
<dd><p><code>:UTF32BE</code>
</p>
</dd>
<dt><code>:UTF-32LE</code></dt>
<dd><p><code>:UTF32LE</code>
</p>
</dd>
<dt><code>:UTF-8</code></dt>
<dd><p><code>:UTF8</code>
</p>
</dd>
<dt><code>:X-MAC-CYRILLIC</code></dt>
<dd><p><code>:|x-mac-cyrillic|</code>
</p>
</dd>
</dl>

<a name="index-open-_005bcl_005d"></a>
<a name="index-with_002dopen_002dfile-_005bcl_005d"></a>
<p>In situations where an external file format designator is required, such
as the <code>:external-format</code> argument in calls to <code>open</code> or
<code>with-open-file</code>, users may supply the name of an encoding to
denote the external format which is applying that encoding to Lisp
characters.
</p>
<p>In addition to the basic encoding for an external format, options
controlling various special cases may be passed, by using a list (whose
first element must be an encoding name and whose rest is a plist) as an
external file format designator.  At present, the only supported key in
the plist is <code>:replacement</code>, where the corresponding value is a
string designator which is used as a replacement when an encoding or
decoding error happens, handling those errors without user intervention;
for example:
</p><div class="lisp">
<pre class="lisp">(with-open-file (i pathname :external-format '(:utf-8 :replacement #\?))
  (read-line i))
</pre></div>
<p>will read the first line of <var>pathname</var>, replacing any invalid utf-8
sequences with question marks.
</p>
<hr>
<a name="Bivalent-Streams"></a>
<div class="header">
<p>
Next: <a href="#Gray-Streams" accesskey="n" rel="next">Gray Streams</a>, Previous: <a href="#External-Formats" accesskey="p" rel="prev">External Formats</a>, Up: <a href="#Streams" accesskey="u" rel="up">Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Bivalent-Streams-1"></a>
<h3 class="section">10.2 Bivalent Streams</h3>

<p>A <em>bivalent stream</em> can be used to read and write both
<code>character</code> and <code>(unsigned-byte 8)</code> values.  A bivalent
stream is created by calling <code>open</code> with the argument <code>:element-type
:default</code>.  On such a stream, both binary and character data can be
read and written with the usual input and output functions.
</p>
<blockquote>
<p>Streams are <em>not</em> created bivalent by default for performance
reasons.  Bivalent streams are incompatible with
<code>fast-read-char</code>, an internal optimization in SBCL&rsquo;s stream
machinery that bulk-converts octets to characters and implements a
fast path through <code>read-char</code>.
</p></blockquote>

<hr>
<a name="Gray-Streams"></a>
<div class="header">
<p>
Next: <a href="#Simple-Streams" accesskey="n" rel="next">Simple Streams</a>, Previous: <a href="#Bivalent-Streams" accesskey="p" rel="prev">Bivalent Streams</a>, Up: <a href="#Streams" accesskey="u" rel="up">Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Gray-Streams-1"></a>
<h3 class="section">10.3 Gray Streams</h3>


<p>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&rsquo;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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Gray-Streams-classes" accesskey="1">Gray Streams classes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Methods-common-to-all-streams" accesskey="2">Methods common to all streams</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Input-stream-methods" accesskey="3">Input stream methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Character-input-stream-methods" accesskey="4">Character input stream methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Output-stream-methods" accesskey="5">Output stream methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Character-output-stream-methods" accesskey="6">Character output stream methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Binary-stream-methods" accesskey="7">Binary stream methods</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Gray-Streams-examples" accesskey="8">Gray Streams examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Gray-Streams-classes"></a>
<div class="header">
<p>
Next: <a href="#Methods-common-to-all-streams" accesskey="n" rel="next">Methods common to all streams</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Gray-Streams-classes-1"></a>
<h4 class="subsection">10.3.1 Gray Streams classes</h4>

<p>The defined Gray Stream classes are these:
</p>
<a name="Class-sb_002dgray_003afundamental_002dstream"></a><dl>
<dt><a name="index-fundamental_002dstream"></a>Class: <strong>fundamental-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-stream, standard-object, stream, t</code>
</p>
<p>Base class for all Gray streams.
</p></dd></dl>
<a name="Class-sb_002dgray_003afundamental_002dinput_002dstream"></a><dl>
<dt><a name="index-fundamental_002dinput_002dstream"></a>Class: <strong>fundamental-input-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-input-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray input streams.
</p></dd></dl>

<p>The function input-stream-p will return true of any generalized
instance of fundamental-input-stream.
</p>
<a name="Class-sb_002dgray_003afundamental_002doutput_002dstream"></a><dl>
<dt><a name="index-fundamental_002doutput_002dstream"></a>Class: <strong>fundamental-output-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-output-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray output streams.
</p></dd></dl>

<p>The function output-stream-p will return true of any generalized
instance of fundamental-output-stream.
</p>
<a name="Class-sb_002dgray_003afundamental_002dbinary_002dstream"></a><dl>
<dt><a name="index-fundamental_002dbinary_002dstream"></a>Class: <strong>fundamental-binary-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-binary-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray streams whose element-type
is a subtype of unsigned-byte or signed-byte.
</p></dd></dl>

<p>Note that instantiable subclasses of fundamental-binary-stream should
provide (or inherit) an applicable method for the generic function
stream-element-type.
</p>
<a name="Class-sb_002dgray_003afundamental_002dcharacter_002dstream"></a><dl>
<dt><a name="index-fundamental_002dcharacter_002dstream"></a>Class: <strong>fundamental-character-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-character-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray streams whose element-type is a subtype of character.
</p></dd></dl>
<a name="Class-sb_002dgray_003afundamental_002dbinary_002dinput_002dstream"></a><dl>
<dt><a name="index-fundamental_002dbinary_002dinput_002dstream"></a>Class: <strong>fundamental-binary-input-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-binary-input-stream, fundamental-input-stream, fundamental-binary-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray input streams whose element-type
is a subtype of unsigned-byte or signed-byte.
</p></dd></dl>
<a name="Class-sb_002dgray_003afundamental_002dbinary_002doutput_002dstream"></a><dl>
<dt><a name="index-fundamental_002dbinary_002doutput_002dstream"></a>Class: <strong>fundamental-binary-output-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-binary-output-stream, fundamental-output-stream, fundamental-binary-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray output streams whose element-type
is a subtype of unsigned-byte or signed-byte.
</p></dd></dl>
<a name="Class-sb_002dgray_003afundamental_002dcharacter_002dinput_002dstream"></a><dl>
<dt><a name="index-fundamental_002dcharacter_002dinput_002dstream"></a>Class: <strong>fundamental-character-input-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-character-input-stream, fundamental-input-stream, fundamental-character-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray input streams whose element-type
is a subtype of character.
</p></dd></dl>
<a name="Class-sb_002dgray_003afundamental_002dcharacter_002doutput_002dstream"></a><dl>
<dt><a name="index-fundamental_002dcharacter_002doutput_002dstream"></a>Class: <strong>fundamental-character-output-stream</strong> <em>[sb-gray]</em></dt>
<dd><p>Class precedence list: <code>fundamental-character-output-stream, fundamental-output-stream, fundamental-character-stream, fundamental-stream, standard-object, stream, t</code>
</p>
<p>Superclass of all Gray output streams whose element-type
is a subtype of character.
</p></dd></dl>

<hr>
<a name="Methods-common-to-all-streams"></a>
<div class="header">
<p>
Next: <a href="#Input-stream-methods" accesskey="n" rel="next">Input stream methods</a>, Previous: <a href="#Gray-Streams-classes" accesskey="p" rel="prev">Gray Streams classes</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Methods-common-to-all-streams-1"></a>
<h4 class="subsection">10.3.2 Methods common to all streams</h4>

<p>These generic functions can be specialized on any generalized instance
of fundamental-stream.
</p>
<a name="Generic_002dFunction-common_002dlisp_003astream_002delement_002dtype"></a><dl>
<dt><a name="index-stream_002delement_002dtype"></a>Generic Function: <strong>stream-element-type</strong> <em>[cl] stream</em></dt>
<dd><p>Return a type specifier for the kind of object returned by the
  <code>stream</code>. The class <code>fundamental-character-stream</code> provides a default method
  which returns <code>character</code>.
</p></dd></dl>
<a name="Generic_002dFunction-common_002dlisp_003aclose"></a><dl>
<dt><a name="index-close"></a>Generic Function: <strong>close</strong> <em>[cl] stream &amp;key abort</em></dt>
<dd><p>Close the given <code>stream</code>. No more I/O may be performed, but
  inquiries may still be made. If <code>:abort</code> is true, an attempt is made
  to clean up the side effects of having created the stream.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dfile_002dposition"></a><dl>
<dt><a name="index-stream_002dfile_002dposition"></a>Generic Function: <strong>stream-file-position</strong> <em>[sb-gray] stream &amp;optional position-spec</em></dt>
<dd><p>Used by <code>file-position</code>. Returns or changes the current position within <code>stream</code>.
</p></dd></dl>



<hr>
<a name="Input-stream-methods"></a>
<div class="header">
<p>
Next: <a href="#Character-input-stream-methods" accesskey="n" rel="next">Character input stream methods</a>, Previous: <a href="#Methods-common-to-all-streams" accesskey="p" rel="prev">Methods common to all streams</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Input-stream-methods-1"></a>
<h4 class="subsection">10.3.3 Input stream methods</h4>

<p>These generic functions may be specialized on any generalized instance
of fundamental-input-stream.
</p>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dclear_002dinput"></a><dl>
<dt><a name="index-stream_002dclear_002dinput"></a>Generic Function: <strong>stream-clear-input</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is like <code>cl:clear-input</code>, but for Gray streams, returning <code>nil</code>.
  The default method does nothing.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dread_002dsequence"></a><dl>
<dt><a name="index-stream_002dread_002dsequence"></a>Generic Function: <strong>stream-read-sequence</strong> <em>[sb-gray] stream seq &amp;optional start end</em></dt>
<dd><p>This is like <code>cl:read-sequence</code>, but for Gray streams.
</p></dd></dl>

<hr>
<a name="Character-input-stream-methods"></a>
<div class="header">
<p>
Next: <a href="#Output-stream-methods" accesskey="n" rel="next">Output stream methods</a>, Previous: <a href="#Input-stream-methods" accesskey="p" rel="prev">Input stream methods</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Character-input-stream-methods-1"></a>
<h4 class="subsection">10.3.4 Character input stream methods</h4>

<p>These generic functions are used to implement subclasses of
fundamental-input-stream:
</p>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dpeek_002dchar"></a><dl>
<dt><a name="index-stream_002dpeek_002dchar"></a>Generic Function: <strong>stream-peek-char</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is used to implement <code>peek-char</code>; this corresponds to <code>peek-type</code> of <code>nil</code>.
  It returns either a character or <code>:eof</code>. The default method calls
  <code>stream-read-char</code> and <code>stream-unread-char</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dread_002dchar_002dno_002dhang"></a><dl>
<dt><a name="index-stream_002dread_002dchar_002dno_002dhang"></a>Generic Function: <strong>stream-read-char-no-hang</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is used to implement <code>read-char-no-hang</code>. It returns either a
  character, or <code>nil</code> if no input is currently available, or <code>:eof</code> if
  end-of-file is reached. The default method provided by
  <code>fundamental-character-input-stream</code> simply calls <code>stream-read-char</code>; this
  is sufficient for file streams, but interactive streams should define
  their own method.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dread_002dchar"></a><dl>
<dt><a name="index-stream_002dread_002dchar"></a>Generic Function: <strong>stream-read-char</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Read one character from the stream. Return either a
  character object, or the symbol <code>:eof</code> if the stream is at end-of-file.
  Every subclass of <code>fundamental-character-input-stream</code> must define a
  method for this function.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dread_002dline"></a><dl>
<dt><a name="index-stream_002dread_002dline"></a>Generic Function: <strong>stream-read-line</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is used by <code>read-line</code>. 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 <code>stream-read-char</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dlisten"></a><dl>
<dt><a name="index-stream_002dlisten"></a>Generic Function: <strong>stream-listen</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is used by <code>listen</code>. It returns true or false. The default method uses
  <code>stream-read-char-no-hang</code> and <code>stream-unread-char</code>. Most streams should
  define their own method since it will usually be trivial and will
  always be more efficient than the default method.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dunread_002dchar"></a><dl>
<dt><a name="index-stream_002dunread_002dchar"></a>Generic Function: <strong>stream-unread-char</strong> <em>[sb-gray] stream character</em></dt>
<dd><p>Undo the last call to <code>stream-read-char</code>, as in <code>unread-char</code>.
  Return <code>nil</code>. Every subclass of <code>fundamental-character-input-stream</code>
  must define a method for this function.
</p></dd></dl>

<hr>
<a name="Output-stream-methods"></a>
<div class="header">
<p>
Next: <a href="#Character-output-stream-methods" accesskey="n" rel="next">Character output stream methods</a>, Previous: <a href="#Character-input-stream-methods" accesskey="p" rel="prev">Character input stream methods</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Output-stream-methods-1"></a>
<h4 class="subsection">10.3.5 Output stream methods</h4>

<p>These generic functions are used to implement subclasses of
fundamental-output-stream:
</p>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dclear_002doutput"></a><dl>
<dt><a name="index-stream_002dclear_002doutput"></a>Generic Function: <strong>stream-clear-output</strong> <em>[sb-gray] stream</em></dt>
<dd><p>This is like <code>cl:clear-output</code>, but for Gray streams: clear the given
  output <code>stream</code>. The default method does nothing.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dfinish_002doutput"></a><dl>
<dt><a name="index-stream_002dfinish_002doutput"></a>Generic Function: <strong>stream-finish-output</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Attempts to ensure that all output sent to the Stream has reached
  its destination, and only then returns false. Implements
  <code>finish-output</code>. The default method does nothing.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dforce_002doutput"></a><dl>
<dt><a name="index-stream_002dforce_002doutput"></a>Generic Function: <strong>stream-force-output</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Attempts to force any buffered output to be sent. Implements
  <code>force-output</code>. The default method does nothing.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dwrite_002dsequence"></a><dl>
<dt><a name="index-stream_002dwrite_002dsequence"></a>Generic Function: <strong>stream-write-sequence</strong> <em>[sb-gray] stream seq &amp;optional start end</em></dt>
<dd><p>This is like <code>cl:write-sequence</code>, but for Gray streams.
</p></dd></dl>

<hr>
<a name="Character-output-stream-methods"></a>
<div class="header">
<p>
Next: <a href="#Binary-stream-methods" accesskey="n" rel="next">Binary stream methods</a>, Previous: <a href="#Output-stream-methods" accesskey="p" rel="prev">Output stream methods</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Character-output-stream-methods-1"></a>
<h4 class="subsection">10.3.6 Character output stream methods</h4>

<p>These generic functions are used to implement subclasses of
fundamental-character-output-stream:
</p>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dadvance_002dto_002dcolumn"></a><dl>
<dt><a name="index-stream_002dadvance_002dto_002dcolumn"></a>Generic Function: <strong>stream-advance-to-column</strong> <em>[sb-gray] stream column</em></dt>
<dd><p>Write enough blank space so that the next character will be
  written at the specified column. Returns true if the operation is
  successful, or <code>nil</code> if it is not supported for this stream. This is
  intended for use by by <code>pprint</code> and <code>format</code> ~T. The default method uses
  <code>stream-line-column</code> and repeated calls to <code>stream-write-char</code> with a
  <code>#space</code> character; it returns <code>nil</code> if <code>stream-line-column</code> returns <code>nil</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dfresh_002dline"></a><dl>
<dt><a name="index-stream_002dfresh_002dline"></a>Generic Function: <strong>stream-fresh-line</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Outputs a new line to the Stream if it is not positioned at the
  beginning of a line. Returns <code>t</code> if it output a new line, nil
  otherwise. Used by <code>fresh-line</code>. The default method uses
  <code>stream-start-line-p</code> and <code>stream-terpri</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dline_002dcolumn"></a><dl>
<dt><a name="index-stream_002dline_002dcolumn"></a>Generic Function: <strong>stream-line-column</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Return the column number where the next character
  will be written, or <code>nil</code> 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 <code>pprint</code> and the <code>format</code> ~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 <code>nil</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dline_002dlength"></a><dl>
<dt><a name="index-stream_002dline_002dlength"></a>Generic Function: <strong>stream-line-length</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Return the stream line length or <code>nil</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dstart_002dline_002dp"></a><dl>
<dt><a name="index-stream_002dstart_002dline_002dp"></a>Generic Function: <strong>stream-start-line-p</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Is <code>stream</code> known to be positioned at the beginning of a line?
  It is permissible for an implementation to always return
  <code>nil</code>. This is used in the implementation of <code>fresh-line</code>. Note that
  while a value of 0 from <code>stream-line-column</code> also indicates the
  beginning of a line, there are cases where <code>stream-start-line-p</code> can be
  meaningfully implemented although <code>stream-line-column</code> can&rsquo;t be. For
  example, for a window using variable-width characters, the column
  number isn&rsquo;t very meaningful, but the beginning of the line does have
  a clear meaning. The default method for <code>stream-start-line-p</code> on class
  <code>fundamental-character-output-stream</code> uses <code>stream-line-column</code>, so if
  that is defined to return <code>nil</code>, then a method should be provided for
  either <code>stream-start-line-p</code> or <code>stream-fresh-line</code>.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dterpri"></a><dl>
<dt><a name="index-stream_002dterpri"></a>Generic Function: <strong>stream-terpri</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Writes an end of line, as for <code>terpri</code>. Returns <code>nil</code>. The default
  method does (<code>stream-write-char</code> stream #NEWLINE).
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dwrite_002dchar"></a><dl>
<dt><a name="index-stream_002dwrite_002dchar"></a>Generic Function: <strong>stream-write-char</strong> <em>[sb-gray] stream character</em></dt>
<dd><p>Write <code>character</code> to <code>stream</code> and return <code>character</code>. Every
  subclass of <code>fundamental-character-output-stream</code> must have a method
  defined for this function.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dwrite_002dstring"></a><dl>
<dt><a name="index-stream_002dwrite_002dstring"></a>Generic Function: <strong>stream-write-string</strong> <em>[sb-gray] stream string &amp;optional start end</em></dt>
<dd><p>This is used by <code>write-string</code>. It writes the string to the stream,
  optionally delimited by start and end, which default to 0 and <code>nil</code>.
  The string argument is returned. The default method provided by
  <code>fundamental-character-output-stream</code> uses repeated calls to
  <code>stream-write-char</code>.
</p></dd></dl>

<hr>
<a name="Binary-stream-methods"></a>
<div class="header">
<p>
Next: <a href="#Gray-Streams-examples" accesskey="n" rel="next">Gray Streams examples</a>, Previous: <a href="#Character-output-stream-methods" accesskey="p" rel="prev">Character output stream methods</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Binary-stream-methods-1"></a>
<h4 class="subsection">10.3.7 Binary stream methods</h4>

<p>The following generic functions are available for subclasses of
fundamental-binary-stream:
</p>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dread_002dbyte"></a><dl>
<dt><a name="index-stream_002dread_002dbyte"></a>Generic Function: <strong>stream-read-byte</strong> <em>[sb-gray] stream</em></dt>
<dd><p>Used by <code>read-byte</code>; returns either an integer, or the symbol <code>:eof</code>
  if the stream is at end-of-file.
</p></dd></dl>
<a name="Generic_002dFunction-sb_002dgray_003astream_002dwrite_002dbyte"></a><dl>
<dt><a name="index-stream_002dwrite_002dbyte"></a>Generic Function: <strong>stream-write-byte</strong> <em>[sb-gray] stream integer</em></dt>
<dd><p>Implements <code>write-byte</code>; writes the integer to the stream and
  returns the integer as the result.
</p></dd></dl>

<hr>
<a name="Gray-Streams-examples"></a>
<div class="header">
<p>
Previous: <a href="#Binary-stream-methods" accesskey="p" rel="prev">Binary stream methods</a>, Up: <a href="#Gray-Streams" accesskey="u" rel="up">Gray Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Gray-Streams-examples-1"></a>
<h4 class="subsection">10.3.8 Gray Streams examples</h4>


<p>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 <code><span class="nolinebreak">stream-read-line</span><!-- /@w --></code>, <code><span class="nolinebreak">stream-write-string</span><!-- /@w --></code>,
<code><span class="nolinebreak">stream-read-sequence</span><!-- /@w --></code>, and <code><span class="nolinebreak">stream-write-sequence</span><!-- /@w --></code>.
</p>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Character-counting-input-stream" accesskey="1">Character counting input stream</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Output-prefixing-character-stream" accesskey="2">Output prefixing character stream</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Character-counting-input-stream"></a>
<div class="header">
<p>
Next: <a href="#Output-prefixing-character-stream" accesskey="n" rel="next">Output prefixing character stream</a>, Up: <a href="#Gray-Streams-examples" accesskey="u" rel="up">Gray Streams examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Character-counting-input-stream-1"></a>
<h4 class="subsubsection">10.3.8.1 Character counting input stream</h4>

<p>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 <code><span class="nolinebreak">stream-read-char</span><!-- /@w --></code> and
<code><span class="nolinebreak">stream-unread-char</span><!-- /@w --></code>.
</p>
<div class="lisp">
<pre class="lisp">(defclass wrapped-stream (fundamental-stream)
  ((stream :initarg :stream :reader stream-of)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod stream-element-type ((stream wrapped-stream))
  (stream-element-type (stream-of stream)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod close ((stream wrapped-stream) &amp;key abort)
  (close (stream-of stream) :abort abort))
</pre><pre class="lisp">

</pre><pre class="lisp">(defclass wrapped-character-input-stream
    (wrapped-stream fundamental-character-input-stream)
  ())
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod stream-read-char ((stream wrapped-character-input-stream))
  (read-char (stream-of stream) nil :eof))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod stream-unread-char ((stream wrapped-character-input-stream)
                               char)
  (unread-char char (stream-of stream)))
</pre><pre class="lisp">

</pre><pre class="lisp">(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)))
</pre><pre class="lisp">

</pre><pre class="lisp">(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)))))
</pre><pre class="lisp">

</pre><pre class="lisp">(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)))
</pre></div>

<p>The default methods for <code><span class="nolinebreak">stream-read-char-no-hang</span><!-- /@w --></code>,
<code><span class="nolinebreak">stream-peek-char</span><!-- /@w --></code>, <code><span class="nolinebreak">stream-listen</span><!-- /@w --></code>,
<code><span class="nolinebreak">stream-clear-input</span><!-- /@w --></code>, <code><span class="nolinebreak">stream-read-line</span><!-- /@w --></code>, and
<code><span class="nolinebreak">stream-read-sequence</span><!-- /@w --></code> should be sufficient (though the last two
will probably be slower than methods that forwarded directly).
</p>
<p>Here&rsquo;s a sample use of this class:
</p>
<div class="lisp">
<pre class="lisp">(with-input-from-string (input &quot;1 2
 3 :foo  &quot;)
  (let ((counted-stream (make-instance 'counting-character-input-stream
                         :stream input)))
    (loop for thing = (read counted-stream) while thing
       unless (numberp thing) do
         (error &quot;Non-number ~S (line ~D, column ~D)&quot; thing
                (line-count-of counted-stream)
                (- (col-count-of counted-stream)
                   (length (format nil &quot;~S&quot; thing))))
       end
       do (print thing))))
</pre><pre class="verbatim">1
2
3
Non-number :FOO (line 2, column 5)
  [Condition of type SIMPLE-ERROR]
</pre></div>

<hr>
<a name="Output-prefixing-character-stream"></a>
<div class="header">
<p>
Previous: <a href="#Character-counting-input-stream" accesskey="p" rel="prev">Character counting input stream</a>, Up: <a href="#Gray-Streams-examples" accesskey="u" rel="up">Gray Streams examples</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Output-prefixing-character-stream-1"></a>
<h4 class="subsubsection">10.3.8.2 Output prefixing character stream</h4>

<p>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&rsquo;s a simple
stream that does this, though without any fancy line-wrapping.  Note
that all character output stream classes must implement
<code><span class="nolinebreak">stream-write-char</span><!-- /@w --></code> and <code><span class="nolinebreak">stream-line-column</span><!-- /@w --></code>.
</p>
<div class="lisp">
<pre class="lisp">(defclass wrapped-stream (fundamental-stream)
  ((stream :initarg :stream :reader stream-of)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod stream-element-type ((stream wrapped-stream))
  (stream-element-type (stream-of stream)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod close ((stream wrapped-stream) &amp;key abort)
  (close (stream-of stream) :abort abort))
</pre><pre class="lisp">

</pre><pre class="lisp">(defclass wrapped-character-output-stream
    (wrapped-stream fundamental-character-output-stream)
  ((col-index :initform 0 :accessor col-index-of)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defmethod stream-line-column ((stream wrapped-character-output-stream))
  (col-index-of stream))
</pre><pre class="lisp">

</pre><pre class="lisp">(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))))
</pre><pre class="lisp">

</pre><pre class="lisp">(defclass prefixed-character-output-stream
    (wrapped-character-output-stream)
  ((prefix :initarg :prefix :reader prefix-of)))
</pre><pre class="lisp">

</pre><pre class="lisp">(defgeneric write-prefix (prefix stream)
  (:method ((prefix string) stream) (write-string prefix stream))
  (:method ((prefix function) stream) (funcall prefix stream)))
</pre><pre class="lisp">

</pre><pre class="lisp">(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)))
</pre></div>

<p>As with the example input stream, this implements only the minimal
protocol.  A production implementation should also provide methods for
at least <code><span class="nolinebreak">stream-write-line</span><!-- /@w --></code>, <code><span class="nolinebreak">stream-write-sequence</span><!-- /@w --></code>.
</p>
<p>And here&rsquo;s a sample use of this class:
</p>
<div class="lisp">
<pre class="lisp">(flet ((format-timestamp (stream)
         (apply #'format stream &quot;[~2@*~2,' D:~1@*~2,'0D:~0@*~2,'0D] &quot;
                (multiple-value-list (get-decoded-time)))))
  (let ((output (make-instance 'prefixed-character-output-stream
                               :stream *standard-output*
                               :prefix #'format-timestamp)))
    (loop for string in '(&quot;abc&quot; &quot;def&quot; &quot;ghi&quot;) do
         (write-line string output)
         (sleep 1))))
</pre><pre class="verbatim">[ 0:30:05] abc
[ 0:30:06] def
[ 0:30:07] ghi
NIL
</pre></div>

<hr>
<a name="Simple-Streams"></a>
<div class="header">
<p>
Previous: <a href="#Gray-Streams" accesskey="p" rel="prev">Gray Streams</a>, Up: <a href="#Streams" accesskey="u" rel="up">Streams</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Simple-Streams-1"></a>
<h3 class="section">10.4 Simple Streams</h3>
<p>Simple streams are an extensible streams protocol that avoids some
problems with Gray streams.
</p>
<p>Documentation about simple streams is available at:
</p>
<p><a href="http://www.franz.com/support/documentation/6.2/doc/streams.htm">http://www.franz.com/support/documentation/6.2/doc/streams.htm</a>
</p>
<p>The implementation should be considered Alpha-quality; the basic
framework is there, but many classes are just stubs at the moment.
</p>
<p>See <samp>SYS:CONTRIB;SB-SIMPLE-STREAMS;SIMPLE-STREAM-TEST.LISP</samp> for
things that should work.
</p>
<p>Known differences to the ACL behaviour:
</p>
<ul>
<li> <code>open</code> not return a simple-stream by default. This can be
adjusted; see default-open-class in the file cl.lisp

</li><li> <code>write-vector</code> is unimplemented.

</li></ul>
<hr>
<a name="Package-Locks"></a>
<div class="header">
<p>
Next: <a href="#Threading" accesskey="n" rel="next">Threading</a>, Previous: <a href="#Streams" accesskey="p" rel="prev">Streams</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Locks-1"></a>
<h2 class="chapter">11 Package Locks</h2>
<a name="index-Packages_002c-locked"></a>

<p>None of the following sections apply to SBCL built without package
locking support.
</p>
<blockquote>
<p><b>warning:</b> The interface described here is experimental: incompatible changes in
future SBCL releases are possible, even expected: the concept of
&ldquo;implementation packages&rdquo; 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.
</p></blockquote>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Package-Lock-Concepts" accesskey="1">Package Lock Concepts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package-Lock-Dictionary" accesskey="2">Package Lock Dictionary</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Package-Lock-Concepts"></a>
<div class="header">
<p>
Next: <a href="#Package-Lock-Dictionary" accesskey="n" rel="next">Package Lock Dictionary</a>, Up: <a href="#Package-Locks" accesskey="u" rel="up">Package Locks</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Lock-Concepts-1"></a>
<h3 class="section">11.1 Package Lock Concepts</h3>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Package-Lock-Overview" accesskey="1">Package Lock Overview</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Implementation-Packages" accesskey="2">Implementation Packages</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package-Lock-Violations" accesskey="3">Package Lock Violations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Package-Locks-in-Compiled-Code" accesskey="4">Package Locks in Compiled Code</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Operations-Violating-Package-Locks" accesskey="5">Operations Violating Package Locks</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Package-Lock-Overview"></a>
<div class="header">
<p>
Next: <a href="#Implementation-Packages" accesskey="n" rel="next">Implementation Packages</a>, Up: <a href="#Package-Lock-Concepts" accesskey="u" rel="up">Package Lock Concepts</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Locking-Overview"></a>
<h4 class="subsection">11.1.1 Package Locking Overview</h4>

<p>Package locks protect against unintentional modifications of a package:
they provide similar protection to user packages as is mandated to
<code>common-lisp</code> package by the ANSI specification. They are not, and
should not be used as, a security measure.
</p>
<p>Newly created packages are by default unlocked (see the <code>:lock</code>
option to <code>defpackage</code>).
</p>
<p>The package <code>common-lisp</code> and SBCL internal implementation
packages are locked by default, including <code>sb-ext</code>.
</p>
<p>It may be beneficial to lock <code>common-lisp-user</code> as well, to
ensure that various libraries don&rsquo;t pollute it without asking,
but this is not currently done by default.
</p>
<hr>
<a name="Implementation-Packages"></a>
<div class="header">
<p>
Next: <a href="#Package-Lock-Violations" accesskey="n" rel="next">Package Lock Violations</a>, Previous: <a href="#Package-Lock-Overview" accesskey="p" rel="prev">Package Lock Overview</a>, Up: <a href="#Package-Lock-Concepts" accesskey="u" rel="up">Package Lock Concepts</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Implementation-Packages-1"></a>
<h4 class="subsection">11.1.2 Implementation Packages</h4>
<a name="index-_002apackage_002a-_005bcl_005d"></a>
<a name="index-defpackage-_005bcl_005d-1"></a>

<p>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 <code>*package*</code> is
bound to one of the implementation packages of the locked package.
</p>
<p>Unless explicitly altered by <code>defpackage</code>,
<code>sb-ext:add-implementation-package</code>, or
<code>sb-ext:remove-implementation-package</code> each package is its own
(only) implementation package.
</p>
<hr>
<a name="Package-Lock-Violations"></a>
<div class="header">
<p>
Next: <a href="#Package-Locks-in-Compiled-Code" accesskey="n" rel="next">Package Locks in Compiled Code</a>, Previous: <a href="#Implementation-Packages" accesskey="p" rel="prev">Implementation Packages</a>, Up: <a href="#Package-Lock-Concepts" accesskey="u" rel="up">Package Lock Concepts</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Lock-Violations-1"></a>
<h4 class="subsection">11.1.3 Package Lock Violations</h4>
<a name="index-package_002dlock_002dviolation-_005bsb_002dext_005d"></a>
<a name="index-package_002dlocked_002derror-_005bsb_002dext_005d"></a>
<a name="index-symbol_002dpackage_002dlocked_002derror-_005bsb_002dext_005d"></a>
<a name="index-package_002derror-_005bcl_005d"></a>

<a name="Lexical-Bindings-and-Declarations"></a>
<h4 class="subsubsection">11.1.3.1 Lexical Bindings and Declarations</h4>
<a name="index-let-_005bcl_005d-1"></a>
<a name="index-let_002a-_005bcl_005d-1"></a>
<a name="index-flet-_005bcl_005d-1"></a>
<a name="index-labels-_005bcl_005d-1"></a>
<a name="index-macrolet-_005bcl_005d"></a>
<a name="index-symbol_002dmacrolet-_005bcl_005d"></a>
<a name="index-declare-_005bcl_005d"></a>
<a name="index-Declarations"></a>
<a name="index-disable_002dpackage_002dlocks-_005bsb_002dext_005d"></a>
<a name="index-enable_002dpackage_002dlocks-_005bsb_002dext_005d"></a>

<p>Lexical bindings or declarations that violate package locks cause a
compile-time warning, and a runtime <code>program-error</code> when the form
that violates package locks would be executed.
</p>
<p>A complete listing of operators affect by this is: <code>let</code>,
<code>let*</code>, <code>flet</code>, <code>labels</code>, <code>macrolet</code>, and
<code>symbol-macrolet</code>, <code>declare</code>.
</p>
<p>Package locks affecting both lexical bindings and declarations can be
disabled locally with <code>sb-ext:disable-package-locks</code> declaration,
and re-enabled with <code>sb-ext:enable-package-locks</code> declaration.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">(in-package :locked)

(defun foo () ...)

(defmacro with-foo (&amp;body body)
  `(locally (declare (disable-package-locks locked:foo))
     (flet ((foo () ...))
       (declare (enable-package-locks locked:foo)) ; re-enable for body
       ,@body)))
</pre></div>

<a name="Other-Operations"></a>
<h4 class="subsubsection">11.1.3.2 Other Operations</h4>

<p>If an non-lexical operation violates a package lock, a continuable
error that is of a subtype of <code>sb-ext:package-lock-violation</code>
(subtype of <code>package-error</code>) is signalled when the operation is
attempted.
</p>
<p>Additional restarts may be established for continuable package lock
violations for interactive use.
</p>
<p>The actual type of the error depends on circumstances that caused the
violation: operations on packages signal errors of type
<code>sb-ext:package-locked-error</code>, and operations on symbols signal
errors of type <code>sb-ext:symbol-package-locked-error</code>.
</p>

<hr>
<a name="Package-Locks-in-Compiled-Code"></a>
<div class="header">
<p>
Next: <a href="#Operations-Violating-Package-Locks" accesskey="n" rel="next">Operations Violating Package Locks</a>, Previous: <a href="#Package-Lock-Violations" accesskey="p" rel="prev">Package Lock Violations</a>, Up: <a href="#Package-Lock-Concepts" accesskey="u" rel="up">Package Lock Concepts</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Locks-in-Compiled-Code-1"></a>
<h4 class="subsection">11.1.4 Package Locks in Compiled Code</h4>

<a name="Interned-Symbols"></a>
<h4 class="subsubsection">11.1.4.1 Interned Symbols</h4>

<p>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.
</p>
<a name="Other-Limitations-on-Compiled-Code"></a>
<h4 class="subsubsection">11.1.4.2 Other Limitations on Compiled Code</h4>

<p>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.
</p>
<p>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.
</p>
<p>In practice all this means that package-locks have a negligible
performance penalty in compiled code as long as they are not violated.
</p>
<hr>
<a name="Operations-Violating-Package-Locks"></a>
<div class="header">
<p>
Previous: <a href="#Package-Locks-in-Compiled-Code" accesskey="p" rel="prev">Package Locks in Compiled Code</a>, Up: <a href="#Package-Lock-Concepts" accesskey="u" rel="up">Package Lock Concepts</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Operations-Violating-Package-Locks-1"></a>
<h4 class="subsection">11.1.5 Operations Violating Package Locks</h4>

<a name="Operations-on-Packages"></a>
<h4 class="subsubsection">11.1.5.1 Operations on Packages</h4>

<p>The following actions cause a package lock violation if the package
operated on is locked, and <code>*package*</code> 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 <code>sb-ext:package-locked-error</code>.
</p>
<ol>
<li> Shadowing a symbol in a package.

</li><li> Importing a symbol to a package.

</li><li> Uninterning a symbol from a package.

</li><li> Exporting a symbol from a package.

</li><li> Unexporting a symbol from a package.

</li><li> Changing the packages used by a package.

</li><li> Renaming a package.

</li><li> Deleting a package.

</li><li> Adding a new package local nickname to a package.

</li><li> Removing an existing package local nickname to a package.

</li></ol>

<a name="Operations-on-Symbols"></a>
<h4 class="subsubsection">11.1.5.2 Operations on Symbols</h4>

<p>Following actions cause a package lock violation if the home package
of the symbol operated on is locked, and <code>*package*</code> is not an
implementation package of that package. Package lock violations caused
by these action signal errors of type
<code>sb-ext:symbol-package-locked-error</code>.
</p>
<p>These actions cause only one package lock violation per lexically
apparent violated package.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">;;; 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)))
</pre></div>

<ol>
<li> Binding or altering its value lexically or dynamically, or
establishing it as a symbol-macro.

<p>Exceptions:
</p>
<ul class="no-bullet">
<li>- 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.

</li><li>- If the symbol is defined as a global dynamic variable, it may be
assigned or bound.

</li></ul>

</li><li> Defining, undefining, or binding it, or its setf name as a function.

<p>Exceptions:
</p>
<ul class="no-bullet">
<li>- 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.

</li></ul>

</li><li> Defining, undefining, or binding it as a macro or compiler macro.

<p>Exceptions:
</p>
<ul class="no-bullet">
<li>- If the symbol is not defined as a function, macro, or special operator
it may be lexically bound as a macro.

</li></ul>

</li><li> Defining it as a type specifier or structure.

</li><li> Defining it as a declaration with a declaration proclamation.

</li><li> Declaring or proclaiming it special.

</li><li> Declaring or proclaiming its type or ftype.

<p>Exceptions:
</p>
<ul class="no-bullet">
<li>- If the symbol may be lexically bound, the type of that binding may be
declared.

</li><li>- If the symbol may be lexically bound as a function, the ftype of that
binding may be declared.

</li></ul>

</li><li> Defining a setf expander for it.

</li><li> Defining it as a method combination type.

</li><li> Using it as the class-name argument to setf of find-class.

</li><li> Defining it as a hash table test using <code>sb-ext:define-hash-table-test</code>.

</li></ol>

<hr>
<a name="Package-Lock-Dictionary"></a>
<div class="header">
<p>
Previous: <a href="#Package-Lock-Concepts" accesskey="p" rel="prev">Package Lock Concepts</a>, Up: <a href="#Package-Locks" accesskey="u" rel="up">Package Locks</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Package-Lock-Dictionary-1"></a>
<h3 class="section">11.2 Package Lock Dictionary</h3>

<dl>
<dt><a name="index-disable_002dpackage_002dlocks"></a>Declaration: <strong>disable-package-locks</strong> <em>[sb-ext]</em></dt>
<dd>
<p>Syntax: <code>(sb-ext:disable-package-locks symbol*)</code>
</p>
<p>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.
</p></dd></dl>

<dl>
<dt><a name="index-enable_002dpackage_002dlocks"></a>Declaration: <strong>enable-package-locks</strong> <em>[sb-ext]</em></dt>
<dd>
<p>Syntax: <code>(sb-ext:enable-package-locks symbol*)</code>
</p>
<p>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 <code>sb-ext:disable-package-locks</code> declaration, or
enabling locks that are already enabled has no effect.
</p></dd></dl>

<a name="Condition-sb_002dext_003apackage_002dlock_002dviolation"></a><dl>
<dt><a name="index-package_002dlock_002dviolation"></a>Condition: <strong>package-lock-violation</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>package-lock-violation, package-error, error, serious-condition, condition, t</code>
</p>
<p>Subtype of <code>cl:package-error</code>. A subtype of this error is signalled
when a package-lock is violated.
</p></dd></dl>
<a name="Condition-sb_002dext_003apackage_002dlocked_002derror"></a><dl>
<dt><a name="index-package_002dlocked_002derror"></a>Condition: <strong>package-locked-error</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>package-locked-error, package-lock-violation, package-error, error, serious-condition, condition, t</code>
</p>
<p>Subtype of <code>sb-ext:package-lock-violation</code>. An error of this type is
signalled when an operation on a package violates a package lock.
</p></dd></dl>
<a name="Condition-sb_002dext_003asymbol_002dpackage_002dlocked_002derror"></a><dl>
<dt><a name="index-symbol_002dpackage_002dlocked_002derror"></a>Condition: <strong>symbol-package-locked-error</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>symbol-package-locked-error, package-lock-violation, package-error, error, serious-condition, condition, t</code>
</p>
<p>Subtype of <code>sb-ext:package-lock-violation</code>. 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
<code>sb-ext:package-locked-error-symbol</code>.
</p></dd></dl>

<dl>
<dt><a name="index-package_002dlocked_002derror_002dsymbol"></a>Function: <strong>package-locked-error-symbol</strong> <em>[sb-ext] symbol-package-locked-error</em></dt>
<dd>
<p>Returns the symbol that caused the <code>symbol-package-locked-error</code>
condition.
</p></dd></dl>

<a name="Function-sb_002dext_003apackage_002dlocked_002dp"></a><dl>
<dt><a name="index-package_002dlocked_002dp"></a>Function: <strong>package-locked-p</strong> <em>[sb-ext] package</em></dt>
<dd><p>Returns <code>t</code> when <code>package</code> is locked, <code>nil</code> otherwise. Signals an error
if <code>package</code> doesn&rsquo;t designate a valid package.
</p></dd></dl>
<a name="Function-sb_002dext_003alock_002dpackage"></a><dl>
<dt><a name="index-lock_002dpackage"></a>Function: <strong>lock-package</strong> <em>[sb-ext] package</em></dt>
<dd><p>Locks <code>package</code> and returns <code>t</code>. Has no effect if <code>package</code> was already
locked. Signals an error if <code>package</code> is not a valid package designator
</p></dd></dl>
<a name="Function-sb_002dext_003aunlock_002dpackage"></a><dl>
<dt><a name="index-unlock_002dpackage"></a>Function: <strong>unlock-package</strong> <em>[sb-ext] package</em></dt>
<dd><p>Unlocks <code>package</code> and returns <code>t</code>. Has no effect if <code>package</code> was already
unlocked. Signals an error if <code>package</code> is not a valid package designator.
</p></dd></dl>
<a name="Function-sb_002dext_003apackage_002dimplemented_002dby_002dlist"></a><dl>
<dt><a name="index-package_002dimplemented_002dby_002dlist"></a>Function: <strong>package-implemented-by-list</strong> <em>[sb-ext] package</em></dt>
<dd><p>Returns a list containing the implementation packages of
<code>package</code>. Signals an error if <code>package</code> is not a valid package designator.
</p></dd></dl>
<a name="Function-sb_002dext_003apackage_002dimplements_002dlist"></a><dl>
<dt><a name="index-package_002dimplements_002dlist"></a>Function: <strong>package-implements-list</strong> <em>[sb-ext] package</em></dt>
<dd><p>Returns the packages that <code>package</code> is an implementation package
of. Signals an error if <code>package</code> is not a valid package designator.
</p></dd></dl>
<a name="Function-sb_002dext_003aadd_002dimplementation_002dpackage"></a><dl>
<dt><a name="index-add_002dimplementation_002dpackage"></a>Function: <strong>add-implementation-package</strong> <em>[sb-ext] packages-to-add &amp;optional package</em></dt>
<dd><p>Adds <code>packages-to-add</code> as implementation packages of <code>package</code>. Signals
an error if <code>package</code> or any of the <code>packages-to-add</code> is not a valid
package designator.
</p></dd></dl>
<a name="Function-sb_002dext_003aremove_002dimplementation_002dpackage"></a><dl>
<dt><a name="index-remove_002dimplementation_002dpackage"></a>Function: <strong>remove-implementation-package</strong> <em>[sb-ext] packages-to-remove &amp;optional package</em></dt>
<dd><p>Removes <code>packages-to-remove</code> from the implementation packages of
<code>package</code>. Signals an error if <code>package</code> or any of the <code>packages-to-remove</code>
is not a valid package designator.
</p></dd></dl>
<a name="Macro-sb_002dext_003awithout_002dpackage_002dlocks"></a><dl>
<dt><a name="index-without_002dpackage_002dlocks"></a>Macro: <strong>without-package-locks</strong> <em>[sb-ext] &amp;body body</em></dt>
<dd><p>Ignores all runtime package lock violations during the execution of
body. Body can begin with declarations.
</p></dd></dl>
<a name="Macro-sb_002dext_003awith_002dunlocked_002dpackages"></a><dl>
<dt><a name="index-with_002dunlocked_002dpackages"></a>Macro: <strong>with-unlocked-packages</strong> <em>[sb-ext] (&amp;rest packages) &amp;body forms</em></dt>
<dd><p>Unlocks <code>packages</code> for the dynamic scope of the body. Signals an
error if any of <code>packages</code> is not a valid package designator.
</p></dd></dl>

<dl>
<dt><a name="index-defpackage-1"></a>Macro: <strong>defpackage</strong> <em>[cl] name [[option]]* &rArr; package</em></dt>
<dd>
<p>Options are extended to include the following:
</p>
<ul>
<li> <code>:lock</code> <var>boolean</var>

<p>If the argument to <code>:lock</code> is <code>t</code>, the package is initially
locked.  If <code>:lock</code> is not provided it defaults to <code>nil</code>.
</p>
</li><li> <code>:implement</code> <var>package-designator</var>*

<p>The package is added as an implementation package to the packages
named. If <code>:implement</code> is not provided, it defaults to the
package itself.
</p></li></ul>

<p>Example:
</p>
<div class="lisp">
<pre class="lisp">(defpackage &quot;FOO&quot; (:export &quot;BAR&quot;) (:lock t) (:implement))
(defpackage &quot;FOO-INT&quot; (:use &quot;FOO&quot;) (:implement &quot;FOO&quot; &quot;FOO-INT&quot;))

;;; is equivalent to

(defpackage &quot;FOO&quot;) (:export &quot;BAR&quot;))
(lock-package &quot;FOO&quot;)
(remove-implementation-package &quot;FOO&quot; &quot;FOO&quot;)
(defpackage &quot;FOO-INT&quot; (:use &quot;BAR&quot;))
(add-implementation-package &quot;FOO-INT&quot; &quot;FOO&quot;)
</pre></div>
</dd></dl>
<hr>
<a name="Threading"></a>
<div class="header">
<p>
Next: <a href="#Timers" accesskey="n" rel="next">Timers</a>, Previous: <a href="#Package-Locks" accesskey="p" rel="prev">Package Locks</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Threading-1"></a>
<h2 class="chapter">12 Threading</h2>

<p>SBCL supports a fairly low-level threading interface that maps onto
the host operating system&rsquo;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.
</p>
<p>Threads are part of the default build on x86[-64]/ARM64 Linux and Windows.
</p>
<p>They are also supported on: x86[-64] Darwin (Mac OS X), x86[-64]
FreeBSD, x86 SunOS (Solaris), PPC Linux, ARM64 Linux. On these
platforms threads must be explicitly enabled at build-time, see
<samp>INSTALL</samp> for directions.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Threading-basics" accesskey="1">Threading basics</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Special-Variables" accesskey="2">Special Variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Atomic-Operations" accesskey="3">Atomic Operations</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Mutex-Support" accesskey="4">Mutex Support</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Semaphores" accesskey="5">Semaphores</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Waitqueue_002fcondition-variables" accesskey="6">Waitqueue/condition variables</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Barriers" accesskey="7">Barriers</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Sessions_002fDebugging" accesskey="8">Sessions/Debugging</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Foreign-threads" accesskey="9">Foreign threads</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Implementation-_0028Linux-x86_002fx86_002d64_0029">Implementation (Linux x86/x86-64)</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Threading-basics"></a>
<div class="header">
<p>
Next: <a href="#Special-Variables" accesskey="n" rel="next">Special Variables</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Threading-basics-1"></a>
<h3 class="section">12.1 Threading basics</h3>

<div class="lisp">
<pre class="lisp">(make-thread (lambda () (write-line &quot;Hello, world&quot;)))
</pre></div>

<a name="Thread-Objects"></a>
<h4 class="subsection">12.1.1 Thread Objects</h4>

<a name="Structure-sb_002dthread_003athread"></a><dl>
<dt><a name="index-thread"></a>Structure: <strong>thread</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>thread, structure-object, t</code>
</p>
<p>Thread type. Do not rely on threads being structs as it may change
in future versions.
</p></dd></dl>
<a name="Variable-sb_002dthread_003a_002acurrent_002dthread_002a"></a><dl>
<dt><a name="index-_002acurrent_002dthread_002a"></a>Variable: <strong>*current-thread*</strong> <em>[sb-thread]</em></dt>
<dd><p>Bound in each thread to the thread itself.
</p></dd></dl>
<a name="Function-sb_002dthread_003alist_002dall_002dthreads"></a><dl>
<dt><a name="index-list_002dall_002dthreads"></a>Function: <strong>list-all-threads</strong> <em>[sb-thread]</em></dt>
<dd><p>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.
</p></dd></dl>
<a name="Function-sb_002dthread_003athread_002dalive_002dp"></a><dl>
<dt><a name="index-thread_002dalive_002dp"></a>Function: <strong>thread-alive-p</strong> <em>[sb-thread] thread</em></dt>
<dd><p>Return <code>t</code> if <code>thread</code> is still alive. Note that the return value is
potentially stale even before the function returns, as the thread may exit at
any time.
</p></dd></dl>
<a name="Function-sb_002dthread_003athread_002dname"></a><dl>
<dt><a name="index-thread_002dname"></a>Function: <strong>thread-name</strong> <em>[sb-thread] instance</em></dt>
<dd><p>Name of the thread. Can be assigned to using <code>setf</code>. Thread names can be
arbitrary printable objects, and need not be unique.
</p></dd></dl>
<a name="Function-sb_002dthread_003amain_002dthread_002dp"></a><dl>
<dt><a name="index-main_002dthread_002dp"></a>Function: <strong>main-thread-p</strong> <em>[sb-thread] &amp;optional thread</em></dt>
<dd><p>True if <code>thread</code>, defaulting to current thread, is the main thread of the process.
</p></dd></dl>
<a name="Function-sb_002dthread_003amain_002dthread"></a><dl>
<dt><a name="index-main_002dthread"></a>Function: <strong>main-thread</strong> <em>[sb-thread]</em></dt>
<dd><p>Returns the main thread of the process.
</p></dd></dl>

<a name="Making_002c-Returning-From_002c-Joining_002c-and-Yielding-Threads"></a>
<h4 class="subsection">12.1.2 Making, Returning From, Joining, and Yielding Threads</h4>

<a name="Function-sb_002dthread_003amake_002dthread"></a><dl>
<dt><a name="index-make_002dthread"></a>Function: <strong>make-thread</strong> <em>[sb-thread] function &amp;key name arguments ephemeral</em></dt>
<dd><p>Create a new thread of <code>name</code> that runs <code>function</code> with the argument
list designator provided (defaults to no argument). Thread exits when
the function returns. The return values of <code>function</code> are kept around
and can be retrieved by <code>join-thread</code>.
</p>
<p>Invoking the initial <code>abort</code> restart established by <code>make-thread</code>
terminates the thread.
</p>
<p>See also: <code>return-from-thread</code>, <code>abort-thread</code>.
</p></dd></dl>
<a name="Macro-sb_002dthread_003areturn_002dfrom_002dthread"></a><dl>
<dt><a name="index-return_002dfrom_002dthread"></a>Macro: <strong>return-from-thread</strong> <em>[sb-thread] values-form &amp;key allow-exit</em></dt>
<dd><p>Unwinds from and terminates the current thread, with values from
<code>values-form</code> as the results visible to <code>join-thread</code>.
</p>
<p>If current thread is the main thread of the process (see
MAIN-THREAD-P), signals an error unless <code>allow-exit</code> is true, as
terminating the main thread would terminate the entire process. If
<code>allow-exit</code> is true, returning from the main thread is equivalent to
calling <code>sb-ext:exit</code> with <code>:code</code> 0 and <code>:abort</code> <code>nil</code>.
</p>
<p>See also: <code>abort-thread</code> and <code>sb-ext:exit</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003aabort_002dthread"></a><dl>
<dt><a name="index-abort_002dthread"></a>Function: <strong>abort-thread</strong> <em>[sb-thread] &amp;key allow-exit</em></dt>
<dd><p>Unwinds from and terminates the current thread abnormally, causing
<code>join-thread</code> on current thread to signal an error unless a
default-value is provided.
</p>
<p>If current thread is the main thread of the process (see
MAIN-THREAD-P), signals an error unless <code>allow-exit</code> is true, as
terminating the main thread would terminate the entire process. If
<code>allow-exit</code> is true, aborting the main thread is equivalent to calling
<code>sb-ext:exit</code> code 1 and <code>:abort</code> <code>nil</code>.
</p>
<p>Invoking the initial <code>abort</code> restart established by <code>make-thread</code> is
equivalent to calling <code>abort-thread</code> in other than main threads.
However, whereas <code>abort</code> restart may be rebound, <code>abort-thread</code> always
unwinds the entire thread. (Behaviour of the initial <code>abort</code> restart for
main thread depends on the <code>:toplevel</code> argument to
<code>sb-ext:save-lisp-and-die</code>.)
</p>
<p>See also: <code>return-from-thread</code> and <code>sb-ext:exit</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003ajoin_002dthread"></a><dl>
<dt><a name="index-join_002dthread"></a>Function: <strong>join-thread</strong> <em>[sb-thread] thread &amp;key default timeout</em></dt>
<dd><p>Suspend current thread until <code>thread</code> exits. Return the result values
of the thread function.
</p>
<p>If <code>thread</code> does not exit within <code>timeout</code> seconds and <code>default</code> is
supplied, return two values: 1) <code>default</code> 2) <code>:timeout</code>. If <code>default</code> is not
supplied, signal a <code>join-thread-error</code> with <code>join-thread-problem</code> equal
to <code>:timeout</code>.
</p>
<p>If <code>thread</code> does not exit normally (i.e. aborted) and <code>default</code> is
supplied, return two values: 1) <code>default</code> 2) <code>:abort</code>. If <code>default</code> is not
supplied, signal a <code>join-thread-error</code> with <code>join-thread-problem</code> equal
to <code>:abort</code>.
</p>
<p>If <code>thread</code> is the current thread, signal a <code>join-thread-error</code> with
<code>join-thread-problem</code> equal to <code>:self-join</code>.
</p>
<p>Trying to join the main thread causes <code>join-thread</code> to block until
<code>timeout</code> occurs or the process exits: when the main thread exits, the
entire process exits.
</p>
<p><code>note:</code> Return convention in case of a timeout is experimental and
subject to change.
</p></dd></dl>
<a name="Function-sb_002dthread_003athread_002dyield"></a><dl>
<dt><a name="index-thread_002dyield"></a>Function: <strong>thread-yield</strong> <em>[sb-thread]</em></dt>
<dd><p>Yield the processor to other threads.
</p></dd></dl>

<a name="Asynchronous-Operations"></a>
<h4 class="subsection">12.1.3 Asynchronous Operations</h4>

<a name="Function-sb_002dthread_003ainterrupt_002dthread"></a><dl>
<dt><a name="index-interrupt_002dthread"></a>Function: <strong>interrupt-thread</strong> <em>[sb-thread] thread function</em></dt>
<dd><p>Interrupt <code>thread</code> and make it run <code>function</code>.
</p>
<p>The interrupt is asynchronous, and can occur anywhere with the exception of
sections protected using <code>sb-sys:without-interrupts</code>.
</p>
<p><code>function</code> is called with interrupts disabled, under
<code>sb-sys:allow-with-interrupts</code>. Since functions such as <code>grab-mutex</code> may try to
enable interrupts internally, in most cases <code>function</code> should either enter
<code>sb-sys:with-interrupts</code> to allow nested interrupts, or
<code>sb-sys:without-interrupts</code> to prevent them completely.
</p>
<p>When a thread receives multiple interrupts, they are executed in the order
they were sent <code>--</code> first in, first out.
</p>
<p>This means that a great degree of care is required to use <code>interrupt-thread</code>
safely and sanely in a production environment. The general recommendation is
to limit uses of <code>interrupt-thread</code> for interactive debugging, banning it
entirely from production environments <code>--</code> it is simply exceedingly hard to use
correctly.
</p>
<p>With those caveats in mind, what you need to know when using it:
</p>
<ul>
<li> If calling <code>function</code> causes a non-local transfer of control (ie. an
   unwind), all normal cleanup forms will be executed.

<p>However, if the interrupt occurs during cleanup forms of an <code>unwind-protect</code>,
   it is just as if that had happened due to a regular <code>go</code>, <code>throw</code>, or
   <code>return-from:</code> the interrupted cleanup form and those following it in the
   same <code>unwind-protect</code> do not get executed.
</p>
<p><code>sbcl</code> tries to keep its own internals asynch-unwind-safe, but this is
   frankly an unreasonable expectation for third party libraries, especially
   given that asynch-unwind-safety does not compose: a function calling
   only asynch-unwind-safe function isn&rsquo;t automatically asynch-unwind-safe.
</p>
<p>This means that in order for an asynch unwind to be safe, the entire
   callstack at the point of interruption needs to be asynch-unwind-safe.
</p>
</li><li> In addition to asynch-unwind-safety you must consider the issue of
   reentrancy. <code>interrupt-thread</code> can cause function that are never normally
   called recursively to be re-entered during their dynamic contour,
   which may cause them to misbehave. (Consider binding of special variables,
   values of global variables, etc.)

</li></ul>
<p>Taken together, these two restrict the &quot;safe&quot; things to do using
<code>interrupt-thread</code> to a fairly minimal set. One useful one <code>--</code> exclusively for
interactive development use is using it to force entry to debugger to inspect
the state of a thread:
</p>
<div class="lisp">
<pre class="lisp">  (interrupt-thread thread #'break)
</pre></div>

<p>Short version: be careful out there.
</p></dd></dl>
<a name="Function-sb_002dthread_003aterminate_002dthread"></a><dl>
<dt><a name="index-terminate_002dthread"></a>Function: <strong>terminate-thread</strong> <em>[sb-thread] thread</em></dt>
<dd><p>Terminate the thread identified by <code>thread</code>, by interrupting it and
causing it to call <code>sb-ext:abort-thread</code> with <code>:allow-exit</code> <code>t</code>.
</p>
<p>The unwind caused by <code>terminate-thread</code> is asynchronous, meaning that
eg. thread executing
</p>
<div class="lisp">
<pre class="lisp">  (let (foo)
     (unwind-protect
         (progn
            (setf foo (get-foo))
            (work-on-foo foo))
       (when foo
         ;; An interrupt occurring inside the cleanup clause
         ;; will cause cleanups from the current UNWIND-PROTECT
         ;; to be dropped.
         (release-foo foo))))
</pre></div>

<p>might miss calling <code>release-foo</code> despite <code>get-foo</code> having returned true if
the interrupt occurs inside the cleanup clause, eg. during execution
of <code>release-foo</code>.
</p>
<p>Thus, in order to write an asynch unwind safe <code>unwind-protect</code> you need
to use <code>without-interrupts:</code>
</p>
<div class="lisp">
<pre class="lisp">  (let (foo)
    (sb-sys:without-interrupts
      (unwind-protect
          (progn
            (setf foo (sb-sys:allow-with-interrupts
                        (get-foo)))
            (sb-sys:with-local-interrupts
              (work-on-foo foo)))
       (when foo
         (release-foo foo)))))
</pre></div>

<p>Since most libraries using <code>unwind-protect</code> do not do this, you should never
assume that unknown code can safely be terminated using <code>terminate-thread</code>.
</p></dd></dl>

<a name="Miscellaneous-Operations"></a>
<h4 class="subsection">12.1.4 Miscellaneous Operations</h4>

<a name="Function-sb_002dthread_003asymbol_002dvalue_002din_002dthread"></a><dl>
<dt><a name="index-symbol_002dvalue_002din_002dthread"></a>Function: <strong>symbol-value-in-thread</strong> <em>[sb-thread] symbol thread &amp;optional errorp</em></dt>
<dd><p>Return the local value of <code>symbol</code> in <code>thread</code>, and a secondary value of <code>t</code>
on success.
</p>
<p>If the value cannot be retrieved (because the thread has exited or because it
has no local binding for NAME) and <code>errorp</code> is true signals an error of type
<code>symbol-value-in-thread-error</code>; if <code>errorp</code> is false returns a primary value of
<code>nil</code>, and a secondary value of <code>nil</code>.
</p>
<p>Can also be used with <code>setf</code> to change the thread-local value of <code>symbol</code>.
</p>
<p><code>symbol-value-in-thread</code> is primarily intended as a debugging tool, and not as a
mechanism for inter-thread communication.
</p></dd></dl>

<a name="Error-Conditions"></a>
<h4 class="subsection">12.1.5 Error Conditions</h4>

<a name="Condition-sb_002dthread_003athread_002derror"></a><dl>
<dt><a name="index-thread_002derror"></a>Condition: <strong>thread-error</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>thread-error, error, serious-condition, condition, t</code>
</p>
<p>Conditions of type <code>thread-error</code> are signalled when thread operations fail.
The offending thread is initialized by the <code>:thread</code> initialization argument and
read by the function <code>thread-error-thread</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003athread_002derror_002dthread"></a><dl>
<dt><a name="index-thread_002derror_002dthread"></a>Function: <strong>thread-error-thread</strong> <em>[sb-thread] condition</em></dt>
<dd><p>Return the offending thread that the <code>thread-error</code> pertains to.
</p></dd></dl>

<a name="Condition-sb_002dthread_003ainterrupt_002dthread_002derror"></a><dl>
<dt><a name="index-interrupt_002dthread_002derror"></a>Condition: <strong>interrupt-thread-error</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>interrupt-thread-error, thread-error, error, serious-condition, condition, t</code>
</p>
<p>Signalled when interrupting a thread fails because the thread has already
exited. The offending thread can be accessed using <code>thread-error-thread</code>.
</p></dd></dl>
<a name="Condition-sb_002dthread_003ajoin_002dthread_002derror"></a><dl>
<dt><a name="index-join_002dthread_002derror"></a>Condition: <strong>join-thread-error</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>join-thread-error, thread-error, error, serious-condition, condition, t</code>
</p>
<p>Signalled when joining a thread fails due to abnormal exit of the thread
to be joined. The offending thread can be accessed using
<code>thread-error-thread</code>.
</p></dd></dl>

<hr>
<a name="Special-Variables"></a>
<div class="header">
<p>
Next: <a href="#Atomic-Operations" accesskey="n" rel="next">Atomic Operations</a>, Previous: <a href="#Threading-basics" accesskey="p" rel="prev">Threading basics</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Special-Variables-1"></a>
<h3 class="section">12.2 Special Variables</h3>

<p>The interaction of special variables with multiple threads is mostly
as one would expect, with behaviour very similar to other
implementations.
</p>
<ul>
<li> global special values are visible across all threads;
</li><li> bindings (e.g. using LET) are local to the thread;
</li><li> threads do not inherit dynamic bindings from the parent thread
</li></ul>

<p>The last point means that
</p>
<div class="lisp">
<pre class="lisp">(defparameter *x* 0)
(let ((*x* 1))
  (sb-thread:make-thread (lambda () (print *x*))))
</pre></div>

<p>prints <code>0</code> and not <code>1</code> as of 0.9.6.
</p>
<hr>
<a name="Atomic-Operations"></a>
<div class="header">
<p>
Next: <a href="#Mutex-Support" accesskey="n" rel="next">Mutex Support</a>, Previous: <a href="#Special-Variables" accesskey="p" rel="prev">Special Variables</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Atomic-Operations-1"></a>
<h3 class="section">12.3 Atomic Operations</h3>

<p>Following atomic operations are particularly useful for implementing
lockless algorithms.
</p>
<a name="Macro-sb_002dext_003aatomic_002ddecf"></a><dl>
<dt><a name="index-atomic_002ddecf"></a>Macro: <strong>atomic-decf</strong> <em>[sb-ext] place &amp;optional diff</em></dt>
<dd><p>Atomically decrements <code>place</code> by <code>diff</code>, and returns the value of <code>place</code> before
the decrement.
</p>
<p><code>place</code> must access one of the following:
</p><ul>
<li> a <code>defstruct</code> slot with declared type <code>(unsigned-byte 64)</code>
   or <code>aref</code> of a <code>(simple-array (unsigned-byte 64) (*))</code>
   The type <code>sb-ext:word</code> can be used for these purposes.
</li><li> <code>car</code> or <code>cdr</code> (respectively <code>first</code> or REST) of a <code>cons</code>.
</li><li> a variable defined using <code>defglobal</code> with a proclaimed type of <code>fixnum</code>.
</li></ul>
<p>Macroexpansion is performed on <code>place</code> before expanding <code>atomic-decf</code>.
</p>
<p>Decrementing is done using modular arithmetic,
which is well-defined over two different domains:
</p><ul>
<li> For structures and arrays, the operation accepts and produces
   an <code>(unsigned-byte 64)</code>, and <code>diff</code> must be of type <code>(signed-byte 64)</code>.
   <code>atomic-decf</code> of #x0 by one results in #xFFFFFFFFFFFFFFFF being stored in <code>place</code>.
</li><li> For other places, the domain is <code>fixnum</code>, and <code>diff</code> must be a <code>fixnum</code>.
   <code>atomic-decf</code> of #x-4000000000000000 by one results in #x3FFFFFFFFFFFFFFF
   being stored in <code>place</code>.

</li></ul>
<p><code>diff</code> defaults to 1.
</p>
<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>
<a name="Macro-sb_002dext_003aatomic_002dincf"></a><dl>
<dt><a name="index-atomic_002dincf"></a>Macro: <strong>atomic-incf</strong> <em>[sb-ext] place &amp;optional diff</em></dt>
<dd><p>Atomically increments <code>place</code> by <code>diff</code>, and returns the value of <code>place</code> before
the increment.
</p>
<p><code>place</code> must access one of the following:
</p><ul>
<li> a <code>defstruct</code> slot with declared type <code>(unsigned-byte 64)</code>
   or <code>aref</code> of a <code>(simple-array (unsigned-byte 64) (*))</code>
   The type <code>sb-ext:word</code> can be used for these purposes.
</li><li> <code>car</code> or <code>cdr</code> (respectively <code>first</code> or REST) of a <code>cons</code>.
</li><li> a variable defined using <code>defglobal</code> with a proclaimed type of <code>fixnum</code>.
</li></ul>
<p>Macroexpansion is performed on <code>place</code> before expanding <code>atomic-incf</code>.
</p>
<p>Incrementing is done using modular arithmetic,
which is well-defined over two different domains:
</p><ul>
<li> For structures and arrays, the operation accepts and produces
   an <code>(unsigned-byte 64)</code>, and <code>diff</code> must be of type <code>(signed-byte 64)</code>.
   <code>atomic-incf</code> of #xFFFFFFFFFFFFFFFF by one results in #x0 being stored in <code>place</code>.
</li><li> For other places, the domain is <code>fixnum</code>, and <code>diff</code> must be a <code>fixnum</code>.
   <code>atomic-incf</code> of #x3FFFFFFFFFFFFFFF by one results in #x-4000000000000000
   being stored in <code>place</code>.

</li></ul>
<p><code>diff</code> defaults to 1.
</p>
<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>
<a name="Macro-sb_002dext_003aatomic_002dpop"></a><dl>
<dt><a name="index-atomic_002dpop"></a>Macro: <strong>atomic-pop</strong> <em>[sb-ext] place</em></dt>
<dd><p>Like <code>pop</code>, but atomic. <code>place</code> may be read multiple times before
the operation completes <code>--</code> the write does not occur until such time
that no other thread modified <code>place</code> between the read and the write.
</p>
<p>Works on all CASable places.
</p></dd></dl>
<a name="Macro-sb_002dext_003aatomic_002dpush"></a><dl>
<dt><a name="index-atomic_002dpush"></a>Macro: <strong>atomic-push</strong> <em>[sb-ext] obj place</em></dt>
<dd><p>Like <code>push</code>, but atomic. <code>place</code> may be read multiple times before
the operation completes <code>--</code> the write does not occur until such time
that no other thread modified <code>place</code> between the read and the write.
</p>
<p>Works on all CASable places.
</p></dd></dl>
<a name="Macro-sb_002dext_003aatomic_002dupdate"></a><dl>
<dt><a name="index-atomic_002dupdate"></a>Macro: <strong>atomic-update</strong> <em>[sb-ext] place update-fn &amp;rest arguments</em></dt>
<dd><p>Updates <code>place</code> atomically to the value returned by calling function
designated by <code>update-fn</code> with <code>arguments</code> and the previous value of <code>place</code>.
</p>
<p><code>place</code> may be read and <code>update-fn</code> evaluated and called multiple times before the
update succeeds: atomicity in this context means that the value of <code>place</code> did
not change between the time it was read, and the time it was replaced with the
computed value.
</p>
<p><code>place</code> can be any place supported by <code>sb-ext:compare-and-swap</code>.
</p>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp">  ;;; Conses T to the head of FOO-LIST.
  (defstruct foo list)
  (defvar *foo* (make-foo))
  (atomic-update (foo-list *foo*) #'cons t)

  (let ((x (cons :count 0)))
     (mapc #'sb-thread:join-thread
           (loop repeat 1000
                 collect (sb-thread:make-thread
                          (lambda ()
                            (loop repeat 1000
                                  do (atomic-update (cdr x) #'1+)
                                     (sleep 0.00001))))))
     ;; Guaranteed to be (:COUNT . 1000000) -- if you replace
     ;; atomic update with (INCF (CDR X)) above, the result becomes
     ;; unpredictable.
     x)
</pre></div>
</dd></dl>
<a name="Macro-sb_002dext_003acompare_002dand_002dswap"></a><dl>
<dt><a name="index-compare_002dand_002dswap"></a>Macro: <strong>compare-and-swap</strong> <em>[sb-ext] place old new</em></dt>
<dd><p>Atomically stores <code>new</code> in <code>place</code> if <code>old</code> matches the current value of <code>place</code>.
Two values are considered to match if they are <code>eq</code>. Returns the previous value
of <code>place:</code> if the returned value is <code>eq</code> to <code>old</code>, the swap was carried out.
</p>
<p><code>place</code> must be an CAS-able place. Built-in CAS-able places are accessor forms
whose <code>car</code> is one of the following:
</p>
<p><code>car</code>, <code>cdr</code>, <code>first</code>, <code>rest</code>, <code>svref</code>, <code>symbol-plist</code>, <code>symbol-value</code>, <code>svref</code>, <code>slot-value</code>
 <code>sb-mop:standard-instance-access</code>, <code>sb-mop:funcallable-standard-instance-access</code>,
</p>
<p>or the name of a <code>defstruct</code> created accessor for a slot whose declared type is
either <code>fixnum</code> or <code>t</code>. Results are unspecified if the slot has a declared type
other than <code>fixnum</code> or <code>t</code>.
</p>
<p>In case of <code>slot-value</code>, if the slot is unbound, <code>slot-unbound</code> is called unless
<code>old</code> is <code>eq</code> to <code>sb-pcl:+slot-unbound+</code> in which case <code>sb-pcl:+slot-unbound+</code> is
returned and <code>new</code> is assigned to the slot. Additionally, the results are
unspecified if there is an applicable method on either
<code>sb-mop:slot-value-using-class</code>, <code>(setf sb-mop:slot-value-using-class)</code>, or
<code>sb-mop:slot-boundp-using-class</code>.
</p>
<p>Additionally, the <code>place</code> can be a anything for which a CAS-expansion has been
specified using <code>defcas</code>, <code>define-cas-expander</code>, or for which a CAS-function has
been defined. (See <code>sb-ext:cas</code> for more information.)
</p></dd></dl>

<a name="CAS-Protocol"></a>
<h4 class="unnumberedsubsec">CAS Protocol</h4>

<p>Our <code>compare-and-swap</code> is user-extensible using a protocol
similar to <code>setf</code>, allowing users to add CAS support to new
places via e.g. <code>defcas</code>.
</p>
<p>At the same time, new atomic operations can be built on top of CAS
using <code>get-cas-expansion</code>. See <code>atomic-update</code>,
<code>atomic-push</code>, and <code>atomic-pop</code> for examples of how to do
this.
</p>
<a name="Macro-sb_002dext_003acas"></a><dl>
<dt><a name="index-cas"></a>Macro: <strong>cas</strong> <em>[sb-ext] place old new</em></dt>
<dd><p>Synonym for <code>compare-and-swap</code>.
</p>
<p>Additionally <code>defun</code>, <code>defgeneric</code>, <code>defmethod</code>, <code>flet</code>, and <code>labels</code> can be also used to
define CAS-functions analogously to SETF-functions:
</p>
<div class="lisp">
<pre class="lisp">  (defvar *foo* nil)

  (defun (cas foo) (old new)
    (cas (symbol-value '*foo*) old new))
</pre></div>

<p>First argument of a <code>cas</code> function is the expected old value, and the second
argument of is the new value. Note that the system provides no automatic
atomicity for <code>cas</code> functions, nor can it verify that they are atomic: it is up
to the implementor of a <code>cas</code> function to ensure its atomicity.
</p>
<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>
<a name="Macro-sb_002dext_003adefine_002dcas_002dexpander"></a><dl>
<dt><a name="index-define_002dcas_002dexpander"></a>Macro: <strong>define-cas-expander</strong> <em>[sb-ext] accessor lambda-list &amp;body body</em></dt>
<dd><p>Analogous to <code>define-setf-expander</code>. Defines a CAS-expansion for <code>accessor</code>.
<code>body</code> must return six values as specified in <code>get-cas-expansion</code>.
</p>
<p>Note that the system provides no automatic atomicity for <code>cas</code> expansion, nor
can it verify that they are atomic: it is up to the implementor of a <code>cas</code>
expansion to ensure its atomicity.
</p>
<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>
<a name="Macro-sb_002dext_003adefcas"></a><dl>
<dt><a name="index-defcas"></a>Macro: <strong>defcas</strong> <em>[sb-ext] accessor lambda-list function &amp;optional docstring</em></dt>
<dd><p>Analogous to short-form <code>defsetf</code>. Defines <code>function</code> as responsible
for compare-and-swap on places accessed using <code>accessor</code>. <code>lambda-list</code>
must correspond to the lambda-list of the accessor.
</p>
<p>Note that the system provides no automatic atomicity for <code>cas</code> expansions
resulting from <code>defcas</code>, nor can it verify that they are atomic: it is up to the
user of <code>defcas</code> to ensure that the function specified is atomic.
</p>
<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>
<a name="Function-sb_002dext_003aget_002dcas_002dexpansion"></a><dl>
<dt><a name="index-get_002dcas_002dexpansion"></a>Function: <strong>get-cas-expansion</strong> <em>[sb-ext] place &amp;optional environment</em></dt>
<dd><p>Analogous to <code>get-setf-expansion</code>. Returns the following six values:
</p>
<ul>
<li> list of temporary variables

</li><li> list of value-forms whose results those variable must be bound

</li><li> temporary variable for the old value of <code>place</code>

</li><li> temporary variable for the new value of <code>place</code>

</li><li> form using the aforementioned temporaries which performs the
   compare-and-swap operation on <code>place</code>

</li><li> form using the aforementioned temporaries with which to perform a volatile
   read of <code>place</code>

</li></ul>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">  (get-cas-expansion '(car x))
  ; =&gt; (#:CONS871), (X), #:OLD872, #:NEW873,
  ;    (SB-KERNEL:%COMPARE-AND-SWAP-CAR #:CONS871 #:OLD872 :NEW873).
  ;    (CAR #:CONS871)

  (defmacro my-atomic-incf (place &amp;optional (delta 1) &amp;environment env)
    (multiple-value-bind (vars vals old new cas-form read-form)
        (get-cas-expansion place env)
     (let ((delta-value (gensym &quot;DELTA&quot;)))
       `(let* (,@(mapcar 'list vars vals)
               (,old ,read-form)
               (,delta-value ,delta)
               (,new (+ ,old ,delta-value)))
          (loop until (eq ,old (setf ,old ,cas-form))
                do (setf ,new (+ ,old ,delta-value)))
          ,new))))
</pre></div>

<p><code>experimental:</code> Interface subject to change.
</p></dd></dl>

<hr>
<a name="Mutex-Support"></a>
<div class="header">
<p>
Next: <a href="#Semaphores" accesskey="n" rel="next">Semaphores</a>, Previous: <a href="#Atomic-Operations" accesskey="p" rel="prev">Atomic Operations</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Mutex-Support-1"></a>
<h3 class="section">12.4 Mutex Support</h3>

<p>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&rsquo;s free. Threads are woken in the order
that they go to sleep.
</p>
<div class="lisp">
<pre class="lisp">(defpackage :demo (:use &quot;CL&quot; &quot;SB-THREAD&quot; &quot;SB-EXT&quot;))

(in-package :demo)

(defvar *a-mutex* (make-mutex :name &quot;my lock&quot;))

(defun thread-fn ()
  (format t &quot;Thread ~A running ~%&quot; *current-thread*)
  (with-mutex (*a-mutex*)
    (format t &quot;Thread ~A got the lock~%&quot; *current-thread*)
    (sleep (random 5)))
  (format t &quot;Thread ~A dropped lock, dying now~%&quot; *current-thread*))

(make-thread #'thread-fn)
(make-thread #'thread-fn)
</pre></div>

<a name="Structure-sb_002dthread_003amutex"></a><dl>
<dt><a name="index-mutex"></a>Structure: <strong>mutex</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>mutex, structure-object, t</code>
</p>
<p>Mutex type.
</p></dd></dl>

<a name="Macro-sb_002dthread_003awith_002dmutex"></a><dl>
<dt><a name="index-with_002dmutex"></a>Macro: <strong>with-mutex</strong> <em>[sb-thread] (mutex &amp;key wait-p timeout value) &amp;body body</em></dt>
<dd><p>Acquire <code>mutex</code> for the dynamic scope of <code>body</code>. If <code>wait-p</code> is true (the default),
and the <code>mutex</code> is not immediately available, sleep until it is available.
</p>
<p>If <code>timeout</code> is given, it specifies a relative timeout, in seconds, on how long
the system should try to acquire the lock in the contested case.
</p>
<p>If the mutex isn&rsquo;t acquired successfully due to either <code>wait-p</code> or <code>timeout</code>, the
body is not executed, and <code>with-mutex</code> returns <code>nil</code>.
</p>
<p>Otherwise body is executed with the mutex held by current thread, and
<code>with-mutex</code> returns the values of <code>body</code>.
</p>
<p>Historically <code>with-mutex</code> also accepted a <code>value</code> argument, which when provided
was used as the new owner of the mutex instead of the current thread. This is
no longer supported: if <code>value</code> is provided, it must be either <code>nil</code> or the
current thread.
</p></dd></dl>
<a name="Macro-sb_002dthread_003awith_002drecursive_002dlock"></a><dl>
<dt><a name="index-with_002drecursive_002dlock"></a>Macro: <strong>with-recursive-lock</strong> <em>[sb-thread] (mutex &amp;key wait-p timeout) &amp;body body</em></dt>
<dd><p>Acquire <code>mutex</code> for the dynamic scope of <code>body</code>.
</p>
<p>If <code>wait-p</code> is true (the default), and the <code>mutex</code> is not immediately available or
held by the current thread, sleep until it is available.
</p>
<p>If <code>timeout</code> is given, it specifies a relative timeout, in seconds, on how long
the system should try to acquire the lock in the contested case.
</p>
<p>If the mutex isn&rsquo;t acquired successfully due to either <code>wait-p</code> or <code>timeout</code>, the
body is not executed, and <code>with-recursive-lock</code> returns <code>nil</code>.
</p>
<p>Otherwise body is executed with the mutex held by current thread, and
<code>with-recursive-lock</code> returns the values of <code>body</code>.
</p>
<p>Unlike <code>with-mutex</code>, which signals an error on attempt to re-acquire an already
held mutex, <code>with-recursive-lock</code> allows recursive lock attempts to succeed.
</p></dd></dl>

<a name="Function-sb_002dthread_003amake_002dmutex"></a><dl>
<dt><a name="index-make_002dmutex"></a>Function: <strong>make-mutex</strong> <em>[sb-thread] &amp;key name</em></dt>
<dd><p>Create a mutex.
</p></dd></dl>
<a name="Function-sb_002dthread_003amutex_002dname"></a><dl>
<dt><a name="index-mutex_002dname"></a>Function: <strong>mutex-name</strong> <em>[sb-thread] instance</em></dt>
<dd><p>The name of the mutex. Setfable.
</p></dd></dl>
<a name="Function-sb_002dthread_003amutex_002downer"></a><dl>
<dt><a name="index-mutex_002downer"></a>Function: <strong>mutex-owner</strong> <em>[sb-thread] mutex</em></dt>
<dd><p>Current owner of the mutex, <code>nil</code> if the mutex is free. Naturally,
this is racy by design (another thread may acquire the mutex after
this function returns), it is intended for informative purposes. For
testing whether the current thread is holding a mutex see
<code>holding-mutex-p</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003amutex_002dvalue"></a><dl>
<dt><a name="index-mutex_002dvalue"></a>Function: <strong>mutex-value</strong> <em>[sb-thread] mutex</em></dt>
<dd><p>Current owner of the mutex, <code>nil</code> if the mutex is free. May return a
stale value, use <code>mutex-owner</code> instead.
</p></dd></dl>
<a name="Function-sb_002dthread_003agrab_002dmutex"></a><dl>
<dt><a name="index-grab_002dmutex"></a>Function: <strong>grab-mutex</strong> <em>[sb-thread] mutex &amp;key waitp timeout</em></dt>
<dd><p>Acquire <code>mutex</code> for the current thread. If <code>waitp</code> is true (the default) and
the mutex is not immediately available, sleep until it is available.
</p>
<p>If <code>timeout</code> is given, it specifies a relative timeout, in seconds, on how long
<code>grab-mutex</code> should try to acquire the lock in the contested case.
</p>
<p>If <code>grab-mutex</code> returns <code>t</code>, the lock acquisition was successful. In case of <code>waitp</code>
being <code>nil</code>, or an expired <code>timeout</code>, <code>grab-mutex</code> may also return <code>nil</code> which denotes
that <code>grab-mutex</code> did -not- acquire the lock.
</p>
<p>Notes:
</p>
<ul>
<li> <code>grab-mutex</code> is not interrupt safe. The correct way to call it is:

<p>(WITHOUT-INTERRUPTS
        ...
        (<code>allow-with-interrupts</code> (<code>grab-mutex</code> ...))
        ...)
</p>
<p><code>without-interrupts</code> is necessary to avoid an interrupt unwinding the call
    while the mutex is in an inconsistent state while <code>allow-with-interrupts</code>
    allows the call to be interrupted from sleep.
</p>
</li><li> <code>(grab-mutex &lt;mutex&gt; :timeout 0.0) </code>differs from
    <code>(grab-mutex &lt;mutex&gt; :waitp nil) </code>in that the former may signal a
    <code>deadline-timeout</code> if the global deadline was due already on entering
    <code>grab-mutex</code>.

<p>The exact interplay of <code>grab-mutex</code> and deadlines are reserved to change in
    future versions.
</p>
</li><li> It is recommended that you use <code>with-mutex</code> instead of calling <code>grab-mutex</code>
    directly.
</li></ul>
</dd></dl>
<a name="Function-sb_002dthread_003arelease_002dmutex"></a><dl>
<dt><a name="index-release_002dmutex"></a>Function: <strong>release-mutex</strong> <em>[sb-thread] mutex &amp;key if-not-owner</em></dt>
<dd><p>Release <code>mutex</code> by setting it to <code>nil</code>. Wake up threads waiting for
this mutex.
</p>
<p><code>release-mutex</code> is not interrupt safe: interrupts should be disabled
around calls to it.
</p>
<p>If the current thread is not the owner of the mutex then it silently
returns without doing anything (if <code>if-not-owner</code> is :PUNT), signals a
<code>warning</code> (if <code>if-not-owner</code> is :WARN), or releases the mutex anyway (if
<code>if-not-owner</code> is :FORCE).
</p></dd></dl>

<hr>
<a name="Semaphores"></a>
<div class="header">
<p>
Next: <a href="#Waitqueue_002fcondition-variables" accesskey="n" rel="next">Waitqueue/condition variables</a>, Previous: <a href="#Mutex-Support" accesskey="p" rel="prev">Mutex Support</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Semaphores-1"></a>
<h3 class="section">12.5 Semaphores</h3>

<p>Semaphores are among other things useful for keeping track of a
countable resource, e.g. messages in a queue, and sleep when the
resource is exhausted.
</p>
<a name="Structure-sb_002dthread_003asemaphore"></a><dl>
<dt><a name="index-semaphore"></a>Structure: <strong>semaphore</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>semaphore, structure-object, t</code>
</p>
<p>Semaphore type. The fact that a <code>semaphore</code> is a <code>structure-object</code>
should be considered an implementation detail, and may change in the
future.
</p></dd></dl>
<a name="Function-sb_002dthread_003amake_002dsemaphore"></a><dl>
<dt><a name="index-make_002dsemaphore"></a>Function: <strong>make-semaphore</strong> <em>[sb-thread] &amp;key name count</em></dt>
<dd><p>Create a semaphore with the supplied <code>count</code> and <code>name</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003asignal_002dsemaphore"></a><dl>
<dt><a name="index-signal_002dsemaphore"></a>Function: <strong>signal-semaphore</strong> <em>[sb-thread] semaphore &amp;optional n</em></dt>
<dd><p>Increment the count of <code>semaphore</code> by <code>n</code>. If there are threads waiting
on this semaphore, then <code>n</code> of them is woken up.
</p></dd></dl>
<a name="Function-sb_002dthread_003await_002don_002dsemaphore"></a><dl>
<dt><a name="index-wait_002don_002dsemaphore"></a>Function: <strong>wait-on-semaphore</strong> <em>[sb-thread] semaphore &amp;key n timeout notification</em></dt>
<dd><p>Decrement the count of <code>semaphore</code> by <code>n</code> if the count would not be negative.
</p>
<p>Else blocks until the semaphore can be decremented. Returns the new count of
<code>semaphore</code> on success.
</p>
<p>If <code>timeout</code> is given, it is the maximum number of seconds to wait. If the count
cannot be decremented in that time, returns <code>nil</code> without decrementing the
count.
</p>
<p>If <code>notification</code> is given, it must be a <code>semaphore-notification</code> object whose
<code>semaphore-notification-status</code> is <code>nil</code>. If <code>wait-on-semaphore</code> succeeds and
decrements the count, the status is set to <code>t</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003atry_002dsemaphore"></a><dl>
<dt><a name="index-try_002dsemaphore"></a>Function: <strong>try-semaphore</strong> <em>[sb-thread] semaphore &amp;optional n notification</em></dt>
<dd><p>Try to decrement the count of <code>semaphore</code> by <code>n</code>. If the count were to
become negative, punt and return <code>nil</code>, otherwise return the new count of
<code>semaphore</code>.
</p>
<p>If <code>notification</code> is given it must be a semaphore notification object
with <code>semaphore-notification-status</code> of <code>nil</code>. If the count is decremented,
the status is set to <code>t</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003asemaphore_002dcount"></a><dl>
<dt><a name="index-semaphore_002dcount"></a>Function: <strong>semaphore-count</strong> <em>[sb-thread] instance</em></dt>
<dd><p>Returns the current count of the semaphore <code>instance</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003asemaphore_002dname"></a><dl>
<dt><a name="index-semaphore_002dname"></a>Function: <strong>semaphore-name</strong> <em>[sb-thread] instance</em></dt>
<dd><p>The name of the semaphore <code>instance</code>. Setfable.
</p></dd></dl>

<a name="Structure-sb_002dthread_003asemaphore_002dnotification"></a><dl>
<dt><a name="index-semaphore_002dnotification"></a>Structure: <strong>semaphore-notification</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>semaphore-notification, structure-object, t</code>
</p>
<p>Semaphore notification object. Can be passed to <code>wait-on-semaphore</code> and
<code>try-semaphore</code> as the <code>:notification</code> argument. Consequences are undefined if
multiple threads are using the same notification object in parallel.
</p></dd></dl>
<a name="Function-sb_002dthread_003amake_002dsemaphore_002dnotification"></a><dl>
<dt><a name="index-make_002dsemaphore_002dnotification"></a>Function: <strong>make-semaphore-notification</strong> <em>[sb-thread]</em></dt>
<dd><p>Constructor for <code>semaphore-notification</code> objects. <code>semaphore-notification-status</code>
is initially <code>nil</code>.
</p></dd></dl>
<a name="Function-sb_002dthread_003asemaphore_002dnotification_002dstatus"></a><dl>
<dt><a name="index-semaphore_002dnotification_002dstatus"></a>Function: <strong>semaphore-notification-status</strong> <em>[sb-thread] semaphore-notification</em></dt>
<dd><p>Returns <code>t</code> if a <code>wait-on-semaphore</code> or <code>try-semaphore</code> using
<code>semaphore-notification</code> has succeeded since the notification object was created
or cleared.
</p></dd></dl>
<a name="Function-sb_002dthread_003aclear_002dsemaphore_002dnotification"></a><dl>
<dt><a name="index-clear_002dsemaphore_002dnotification"></a>Function: <strong>clear-semaphore-notification</strong> <em>[sb-thread] semaphore-notification</em></dt>
<dd><p>Resets the <code>semaphore-notification</code> object for use with another call to
<code>wait-on-semaphore</code> or <code>try-semaphore</code>.
</p></dd></dl>

<hr>
<a name="Waitqueue_002fcondition-variables"></a>
<div class="header">
<p>
Next: <a href="#Barriers" accesskey="n" rel="next">Barriers</a>, Previous: <a href="#Semaphores" accesskey="p" rel="prev">Semaphores</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Waitqueue_002fcondition-variables-1"></a>
<h3 class="section">12.6 Waitqueue/condition variables</h3>

<p>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&rsquo;s true. For example: you have a shared
queue, a writer process checking &ldquo;queue is empty&rdquo; and one or more
readers that need to know when &ldquo;queue is not empty&rdquo;. It sounds
simple, but is astonishingly easy to deadlock if another process runs
when you weren&rsquo;t expecting it to.
</p>
<p>There are three components:
</p>
<ul>
<li> the condition itself (not represented in code)

</li><li> the condition variable (a.k.a. waitqueue) which proxies for it

</li><li> a lock to hold while testing the condition
</li></ul>

<p>Important stuff to be aware of:
</p>
<ul>
<li> 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;

</li><li> likewise, you must be holding the mutex around calls to
condition-notify;

</li><li> 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.

</li></ul>

<div class="lisp">
<pre class="lisp">(defvar *buffer-queue* (make-waitqueue))
(defvar *buffer-lock* (make-mutex :name &quot;buffer lock&quot;))

(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 &quot;reader ~A woke, read ~A~%&quot;
                *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)
</pre></div>

<a name="Structure-sb_002dthread_003awaitqueue"></a><dl>
<dt><a name="index-waitqueue"></a>Structure: <strong>waitqueue</strong> <em>[sb-thread]</em></dt>
<dd><p>Class precedence list: <code>waitqueue, structure-object, t</code>
</p>
<p>Waitqueue type.
</p></dd></dl>
<a name="Function-sb_002dthread_003amake_002dwaitqueue"></a><dl>
<dt><a name="index-make_002dwaitqueue"></a>Function: <strong>make-waitqueue</strong> <em>[sb-thread] &amp;key name</em></dt>
<dd><p>Create a waitqueue.
</p></dd></dl>
<a name="Function-sb_002dthread_003awaitqueue_002dname"></a><dl>
<dt><a name="index-waitqueue_002dname"></a>Function: <strong>waitqueue-name</strong> <em>[sb-thread] instance</em></dt>
<dd><p>The name of the waitqueue. Setfable.
</p></dd></dl>
<a name="Function-sb_002dthread_003acondition_002dwait"></a><dl>
<dt><a name="index-condition_002dwait"></a>Function: <strong>condition-wait</strong> <em>[sb-thread] queue mutex &amp;key timeout</em></dt>
<dd><p>Atomically release <code>mutex</code> and start waiting on <code>queue</code> until another thread
wakes us up using either <code>condition-notify</code> or <code>condition-broadcast</code> on
<code>queue</code>, at which point we re-acquire <code>mutex</code> and return <code>t</code>.
</p>
<p>Spurious wakeups are possible.
</p>
<p>If <code>timeout</code> is given, it is the maximum number of seconds to wait,
including both waiting for the wakeup and the time to re-acquire
<code>mutex</code>. When neither a wakeup nor a re-acquisition occurs within the
given time, returns <code>nil</code> without re-acquiring <code>mutex</code>.
</p>
<p>If <code>condition-wait</code> unwinds, it may do so with or without <code>mutex</code> being
held.
</p>
<p>Important: Since <code>condition-wait</code> may return without <code>condition-notify</code> or
<code>condition-broadcast</code> having occurred, the correct way to write code
that uses <code>condition-wait</code> is to loop around the call, checking the
associated data:
</p>
<div class="lisp">
<pre class="lisp">  (defvar *data* nil)
  (defvar *queue* (make-waitqueue))
  (defvar *lock* (make-mutex))

  ;; Consumer
  (defun pop-data (&amp;optional timeout)
    (with-mutex (*lock*)
      (loop until *data*
            do (or (condition-wait *queue* *lock* :timeout timeout)
                   ;; Lock not held, must unwind without touching *data*.
                   (return-from pop-data nil)))
      (pop *data*)))

  ;; Producer
  (defun push-data (data)
    (with-mutex (*lock*)
      (push data *data*)
      (condition-notify *queue*)))
</pre></div>
</dd></dl>
<a name="Function-sb_002dthread_003acondition_002dnotify"></a><dl>
<dt><a name="index-condition_002dnotify"></a>Function: <strong>condition-notify</strong> <em>[sb-thread] queue &amp;optional n</em></dt>
<dd><p>Notify <code>n</code> threads waiting on <code>queue</code>.
</p>
<p><code>important:</code> The same mutex that is used in the corresponding <code>condition-wait</code>
must be held by this thread during this call.
</p></dd></dl>
<a name="Function-sb_002dthread_003acondition_002dbroadcast"></a><dl>
<dt><a name="index-condition_002dbroadcast"></a>Function: <strong>condition-broadcast</strong> <em>[sb-thread] queue</em></dt>
<dd><p>Notify all threads waiting on <code>queue</code>.
</p>
<p><code>important:</code> The same mutex that is used in the corresponding <code>condition-wait</code>
must be held by this thread during this call.
</p></dd></dl>

<hr>
<a name="Barriers"></a>
<div class="header">
<p>
Next: <a href="#Sessions_002fDebugging" accesskey="n" rel="next">Sessions/Debugging</a>, Previous: <a href="#Waitqueue_002fcondition-variables" accesskey="p" rel="prev">Waitqueue/condition variables</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Barriers-1"></a>
<h3 class="section">12.7 Barriers</h3>

<p>These are based on the Linux kernel barrier design, which is in turn
based on the Alpha CPU memory model. They are presently implemented
for x86, x86-64, PPC, and ARM64 systems, and behave as compiler
barriers on all other CPUs.
</p>
<p>In addition to explicit use of the <code>sb-thread:barrier</code> macro, the
following functions and macros also serve as <code>:memory</code> barriers:
</p>
<ul>
<li> <code>sb-ext:atomic-decf</code>, <code>sb-ext:atomic-incf</code>, <code>sb-ext:atomic-push</code>,
and <code>sb-ext:atomic-pop</code>.
</li><li> <code>sb-ext:compare-and-swap</code>.
</li><li> <code>sb-thread:grab-mutex</code>, <code>sb-thread:release-mutex</code>,
<code>sb-thread:with-mutex</code> and <code>sb-thread:with-recursive-lock</code>.
</li><li> <code>sb-thread:signal-semaphore</code>, <code>sb-thread:try-semaphore</code> and
<code>sb-thread:wait-on-semaphore</code>.
</li><li> <code>sb-thread:condition-wait</code>, <code>sb-thread:condition-notify</code> and
<code>sb-thread:condition-broadcast</code>.
</li></ul>

<a name="Macro-sb_002dthread_003abarrier"></a><dl>
<dt><a name="index-barrier"></a>Macro: <strong>barrier</strong> <em>[sb-thread] (kind) &amp;body forms</em></dt>
<dd><p>Insert a barrier in the code stream, preventing some sort of
reordering.
</p>
<p><code>kind</code> should be one of:
</p>

<dl compact="compact">
<dt><em><code>:compiler</code></em></dt>
<dd><p>Prevent the compiler from reordering memory access across the
    barrier.
</p>
</dd>
<dt><em><code>:memory</code></em></dt>
<dd><p>Prevent the cpu from reordering any memory access across the
    barrier.
</p>
</dd>
<dt><em><code>:read</code></em></dt>
<dd><p>Prevent the cpu from reordering any read access across the
    barrier.
</p>
</dd>
<dt><em><code>:write</code></em></dt>
<dd><p>Prevent the cpu from reordering any write access across the
    barrier.
</p>
</dd>
<dt><em><code>:data-dependency</code></em></dt>
<dd><p>Prevent the cpu from reordering dependent memory reads across the
    barrier (requiring reads before the barrier to complete before any
    reads after the barrier that depend on them).  This is a weaker
    form of the <code>:read</code> barrier.
</p>
</dd>
</dl>

<p><code>forms</code> is an implicit <code>progn</code>, evaluated before the barrier.  <code>barrier</code>
returns the values of the last form in <code>forms</code>.
</p>
<p>The file &quot;memory-barriers.txt&quot; in the Linux kernel documentation is
highly recommended reading for anyone programming at this level.
</p></dd></dl>

<hr>
<a name="Sessions_002fDebugging"></a>
<div class="header">
<p>
Next: <a href="#Foreign-threads" accesskey="n" rel="next">Foreign threads</a>, Previous: <a href="#Barriers" accesskey="p" rel="prev">Barriers</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Sessions_002fDebugging-1"></a>
<h3 class="section">12.8 Sessions/Debugging</h3>

<p>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 <em>sessions</em> such that each
view has its own collection of foreground/background/stopped threads.
A thread which wishes to create a new session can use
<code>sb-thread:with-new-session</code> to remove itself from the current
session (which it shares with its parent and siblings) and create a
fresh one.
# See also <code>sb-thread:make-listener-thread</code>.
</p>
<p>Within a single session, threads arbitrate between themselves for the
user&rsquo;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 <code>sb-thread:get-foreground</code>
(which may block) and <code>sb-thread:release-foreground</code>.
</p>
<hr>
<a name="Foreign-threads"></a>
<div class="header">
<p>
Next: <a href="#Implementation-_0028Linux-x86_002fx86_002d64_0029" accesskey="n" rel="next">Implementation (Linux x86/x86-64)</a>, Previous: <a href="#Sessions_002fDebugging" accesskey="p" rel="prev">Sessions/Debugging</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Foreign-threads-1"></a>
<h3 class="section">12.9 Foreign threads</h3>

<p>Direct calls to <code>pthread_create</code> (instead of <code>MAKE-THREAD</code>)
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&rsquo;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.
</p>
<p>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
<code>--lose-on-corruption</code>, see <a href="#Runtime-Options">Runtime Options</a>.
</p>
<hr>
<a name="Implementation-_0028Linux-x86_002fx86_002d64_0029"></a>
<div class="header">
<p>
Previous: <a href="#Foreign-threads" accesskey="p" rel="prev">Foreign threads</a>, Up: <a href="#Threading" accesskey="u" rel="up">Threading</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Implementation-_0028Linux-x86_002fx86_002d64_0029-1"></a>
<h3 class="section">12.10 Implementation (Linux x86/x86-64)</h3>

<p>Threading is implemented using pthreads and some Linux specific bits
like futexes.
</p>
<p>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.
</p>
<p>Queues require the <code>sys_futex()</code> system call to be available:
this is the reason for the NPTL requirement.  We test at runtime that
this system call exists.
</p>
<p>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.
</p>
<p>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.
</p>
<p>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&rsquo;s intr key
(typically <kbd>Control-C</kbd>) will interrupt all processes in the
foreground process group, including Lisp threads that SBCL considers
to be notionally &lsquo;background&rsquo;.  This is undesirable, so background
threads are set to ignore the SIGINT signal.
</p>
<p><code>sb-thread:make-listener-thread</code> in addition to creating a new
Lisp session makes a new POSIX session, so that pressing
<kbd>Control-C</kbd> in one window will not interrupt another listener -
this has been found to be embarrassing.
</p><hr>
<a name="Timers"></a>
<div class="header">
<p>
Next: <a href="#Networking" accesskey="n" rel="next">Networking</a>, Previous: <a href="#Threading" accesskey="p" rel="prev">Threading</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Timers-1"></a>
<h2 class="chapter">13 Timers</h2>

<p>SBCL supports a system-wide event scheduler implemented on top of
<code>setitimer</code> that also works with threads but does not require a
separate scheduler thread.
</p>
<p>The following example schedules a timer that writes &ldquo;Hello, word&rdquo; after
two seconds.
</p>
<div class="lisp">
<pre class="lisp">(schedule-timer (make-timer (lambda ()
                              (write-line &quot;Hello, world&quot;)
                              (force-output)))
                2)
</pre></div>

<p>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:
</p>
<div class="lisp">
<pre class="lisp">(defvar *foo* nil)

(defun show-foo ()
  (format t &quot;~&amp;foo=~S~%&quot; *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)))
</pre></div>

<a name="Timer-Dictionary"></a>
<h3 class="section">13.1 Timer Dictionary</h3>

<a name="Structure-sb_002dext_003atimer"></a><dl>
<dt><a name="index-timer"></a>Structure: <strong>timer</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>timer, structure-object, t</code>
</p>
<p>Timer type. Do not rely on timers being structs as it may change in
future versions.
</p></dd></dl>
<a name="Function-sb_002dext_003amake_002dtimer"></a><dl>
<dt><a name="index-make_002dtimer"></a>Function: <strong>make-timer</strong> <em>[sb-ext] function &amp;key name thread</em></dt>
<dd><p>Create a timer that runs <code>function</code> when triggered.
</p>
<p>If a <code>thread</code> is supplied, <code>function</code> is run in that thread. If <code>thread</code> is
<code>t</code>, a new thread is created for <code>function</code> each time the timer is
triggered. If <code>thread</code> is <code>nil</code>, <code>function</code> is run in an unspecified thread.
</p>
<p>When <code>thread</code> is not <code>t</code>, <code>interrupt-thread</code> is used to run <code>function</code> and the
ordering guarantees of <code>interrupt-thread</code> apply. In that case, <code>function</code>
runs with interrupts disabled but <code>with-interrupts</code> is allowed.
</p></dd></dl>
<a name="Function-sb_002dext_003atimer_002dname"></a><dl>
<dt><a name="index-timer_002dname"></a>Function: <strong>timer-name</strong> <em>[sb-ext] timer</em></dt>
<dd><p>Return the name of <code>timer</code>.
</p></dd></dl>
<a name="Function-sb_002dext_003atimer_002dscheduled_002dp"></a><dl>
<dt><a name="index-timer_002dscheduled_002dp"></a>Function: <strong>timer-scheduled-p</strong> <em>[sb-ext] timer &amp;key delta</em></dt>
<dd><p>See if <code>timer</code> will still need to be triggered after <code>delta</code> seconds
from now. For timers with a repeat interval it returns true.
</p></dd></dl>
<a name="Function-sb_002dext_003aschedule_002dtimer"></a><dl>
<dt><a name="index-schedule_002dtimer"></a>Function: <strong>schedule-timer</strong> <em>[sb-ext] timer time &amp;key repeat-interval absolute-p catch-up</em></dt>
<dd><p>Schedule <code>timer</code> to be triggered at <code>time</code>. If <code>absolute-p</code> then <code>time</code> is
universal time, but non-integral values are also allowed, else <code>time</code> is
measured as the number of seconds from the current time.
</p>
<p>If <code>repeat-interval</code> is given, <code>timer</code> is automatically rescheduled upon
expiry.
</p>
<p>If <code>repeat-interval</code> is non-NIL, the Boolean <code>catch-up</code> controls whether
<code>timer</code> will &quot;catch up&quot; by repeatedly calling its function without
delay in case calls are missed because of a clock discontinuity such
as a suspend and resume cycle of the computer. The default is <code>nil</code>,
i.e. do not catch up.
</p></dd></dl>
<a name="Function-sb_002dext_003aunschedule_002dtimer"></a><dl>
<dt><a name="index-unschedule_002dtimer"></a>Function: <strong>unschedule-timer</strong> <em>[sb-ext] timer</em></dt>
<dd><p>Cancel <code>timer</code>. Once this function returns it is guaranteed that
<code>timer</code> shall not be triggered again and there are no unfinished
triggers.
</p></dd></dl>
<a name="Function-sb_002dext_003alist_002dall_002dtimers"></a><dl>
<dt><a name="index-list_002dall_002dtimers"></a>Function: <strong>list-all-timers</strong> <em>[sb-ext]</em></dt>
<dd><p>Return a list of all timers in the system.
</p></dd></dl>
<hr>
<a name="Networking"></a>
<div class="header">
<p>
Next: <a href="#Profiling" accesskey="n" rel="next">Profiling</a>, Previous: <a href="#Timers" accesskey="p" rel="prev">Timers</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Networking-1"></a>
<h2 class="chapter">14 Networking</h2>
<a name="index-Sockets_002c-Networking"></a>

<p>The <code>sb-bsd-sockets</code> module provides a thinly disguised BSD
socket API for SBCL. Ideas have been stolen from the BSD socket API
for C and Graham Barr&rsquo;s IO::Socket classes for Perl.
</p>
<p>Sockets are represented as CLOS objects, and the API naming
conventions attempt to balance between the BSD names and good lisp style.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Sockets-Overview" accesskey="1">Sockets Overview</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#General-Sockets" accesskey="2">General Sockets</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Methods applicable to all sockets
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Socket-Options" accesskey="3">Socket Options</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#INET-Domain-Sockets" accesskey="4">INET Domain Sockets</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Local-_0028Unix_0029-Domain-Sockets" accesskey="5">Local (Unix) Domain Sockets</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Name-Service" accesskey="6">Name Service</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Sockets-Overview"></a>
<div class="header">
<p>
Next: <a href="#General-Sockets" accesskey="n" rel="next">General Sockets</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Sockets-Overview-1"></a>
<h3 class="section">14.1 Sockets Overview</h3>

<p>Most of the functions are modelled on the BSD socket API.  BSD sockets
are widely supported, portably <em>(&ldquo;portable&rdquo; by Unix standards, at least)</em>
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:
</p>
<ul>
<li> Where the C API would typically return -1 and set <code>errno</code>,
<code>sb-bsd-sockets</code> signals an error. All the errors are subclasses
of <code>sb-bsd-sockets:socket-condition</code> and generally correspond one
for one with possible <code>errno</code> values.

</li><li> We use multiple return values in many places where the C API would use
pass-by-reference values.

</li><li> We can often avoid supplying an explicit <em>length</em> argument to
functions because we already know how long the argument is.

</li><li> IP addresses and ports are represented in slightly friendlier fashion
than &quot;network-endian integers&quot;.

</li></ul>

<hr>
<a name="General-Sockets"></a>
<div class="header">
<p>
Next: <a href="#Socket-Options" accesskey="n" rel="next">Socket Options</a>, Previous: <a href="#Sockets-Overview" accesskey="p" rel="prev">Sockets Overview</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="General-Sockets-1"></a>
<h3 class="section">14.2 General Sockets</h3>

<a name="Class-sb_002dbsd_002dsockets_003asocket"></a><dl>
<dt><a name="index-socket"></a>Class: <strong>socket</strong> <em>[sb-bsd-sockets]</em></dt>
<dd><p>Class precedence list: <code>socket, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>protocol</code> &mdash; initarg: <code>:protocol<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-bsd-sockets:socket-protocol</span><!-- /@w --></code>

<p>Protocol used by the socket. If a
keyword, the symbol-name of the keyword will be passed to
<code>get-protocol-by-name</code> downcased, and the returned value used as
protocol. Other values are used as-is.
</p></li><li> <code>type</code> &mdash; initarg: <code>:type<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-bsd-sockets:socket-type</span><!-- /@w --></code>

<p>Type of the socket: <code>:stream</code> or <code>:datagram</code>.
</p></li></ul>

<p>Common superclass of all sockets, not meant to be
directly instantiated.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dbind"></a><dl>
<dt><a name="index-socket_002dbind"></a>Generic Function: <strong>socket-bind</strong> <em>[sb-bsd-sockets] socket &amp;rest address</em></dt>
<dd><p>Bind <code>socket</code> to <code>address</code>, which may vary according to socket family.
For the <code>inet</code> family, pass <code>address</code> and <code>port</code> as two arguments; for <code>file</code>
address family sockets, pass the filename string.  See also bind(2)
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002daccept"></a><dl>
<dt><a name="index-socket_002daccept"></a>Generic Function: <strong>socket-accept</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Perform the accept(2) call, returning a newly-created connected
socket and the peer address as multiple values
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dconnect"></a><dl>
<dt><a name="index-socket_002dconnect"></a>Generic Function: <strong>socket-connect</strong> <em>[sb-bsd-sockets] socket &amp;rest address</em></dt>
<dd><p>Perform the connect(2) call to connect <code>socket</code> to a remote <code>peer</code>.
No useful return value.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dpeername"></a><dl>
<dt><a name="index-socket_002dpeername"></a>Generic Function: <strong>socket-peername</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return SOCKET&rsquo;s peer; depending on the address family this may
return multiple values
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dname"></a><dl>
<dt><a name="index-socket_002dname"></a>Generic Function: <strong>socket-name</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the address (as vector of bytes) and port that <code>socket</code> is
bound to, as multiple values.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dreceive"></a><dl>
<dt><a name="index-socket_002dreceive"></a>Generic Function: <strong>socket-receive</strong> <em>[sb-bsd-sockets] socket buffer length &amp;key oob peek waitall dontwait element-type</em></dt>
<dd><p>Read <code>length</code> octets from <code>socket</code> into <code>buffer</code> (or a freshly-consed
buffer if NIL), using recvfrom(2). If <code>length</code> is <code>nil</code>, the length of
<code>buffer</code> is used, so at least one of these two arguments must be
non-NIL. If <code>buffer</code> 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.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dsend"></a><dl>
<dt><a name="index-socket_002dsend"></a>Generic Function: <strong>socket-send</strong> <em>[sb-bsd-sockets] socket buffer length &amp;key address external-format oob eor dontroute dontwait nosignal</em></dt>
<dd><p>Send <code>length</code> octets from <code>buffer</code> into <code>socket</code>, using sendto(2). If
<code>buffer</code> is a string, it will converted to octets according to
<code>external-format</code>. If <code>length</code> is <code>nil</code>, the length of the octet buffer is
used. The format of <code>address</code> depends on the socket type (for example
for <code>inet</code> domain sockets it would be a list of an <code>ip</code> address and a
port). If no socket address is provided, send(2) will be called
instead. Returns the number of octets written.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dlisten"></a><dl>
<dt><a name="index-socket_002dlisten"></a>Generic Function: <strong>socket-listen</strong> <em>[sb-bsd-sockets] socket backlog</em></dt>
<dd><p>Mark <code>socket</code> as willing to accept incoming connections.  The
integer <code>backlog</code> defines the maximum length that the queue of pending
connections may grow to before new connection attempts are refused.
See also listen(2)
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dopen_002dp"></a><dl>
<dt><a name="index-socket_002dopen_002dp"></a>Generic Function: <strong>socket-open-p</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return true if <code>socket</code> is open; otherwise, return false.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dclose"></a><dl>
<dt><a name="index-socket_002dclose"></a>Generic Function: <strong>socket-close</strong> <em>[sb-bsd-sockets] socket &amp;key abort</em></dt>
<dd><p>Close <code>socket</code>, unless it was already closed.
</p>
<p>If <code>socket-make-stream</code> has been called, calls <code>close</code> using <code>abort</code> on that
stream.  Otherwise closes the socket file descriptor using
close(2).
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dshutdown"></a><dl>
<dt><a name="index-socket_002dshutdown"></a>Generic Function: <strong>socket-shutdown</strong> <em>[sb-bsd-sockets] socket &amp;key direction</em></dt>
<dd><p>Indicate that no communication in <code>direction</code> will be performed on
<code>socket</code>.
</p>
<p><code>direction</code> has to be one of <code>:input</code>, <code>:output</code> or <code>:io</code>.
</p>
<p>After a shutdown, no input and/or output of the indicated <code>direction</code>
can be performed on <code>socket</code>.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003asocket_002dmake_002dstream"></a><dl>
<dt><a name="index-socket_002dmake_002dstream"></a>Generic Function: <strong>socket-make-stream</strong> <em>[sb-bsd-sockets] socket &amp;key input output element-type external-format buffering timeout auto-close serve-events</em></dt>
<dd><p>Find or create a <code>stream</code> that can be used for <code>io</code> on <code>socket</code> (which
must be connected).  Specify whether the stream is for <code>input</code>, <code>output</code>,
or both (it is an error to specify neither).
</p>
<p><code>element-type</code> and <code>external-format</code> are as per <code>open</code>.
</p>
<p><code>timeout</code> specifies a read timeout for the stream.
</p></dd></dl>
<a name="Method-sb_002dbsd_002dsockets_003asocket_002dmake_002dstream-_0028_0028socket-socket_0029-_0026key-input-output--_0028element_002dtype-_0027character_0029-_0028buffering-full_0029--_0028external_002dformat-default_0029-timeout-auto_002dclose--serve_002devents_0029"></a><dl>
<dt><a name="index-socket_002dmake_002dstream-1"></a>Method: <strong>socket-make-stream</strong> <em>[sb-bsd-sockets] (socket socket) &amp;key input output (element-type (quote character)) (buffering full) (external-format default) timeout auto-close serve-events</em></dt>
<dd><p>Default method for <code>socket</code> objects.
</p>
<p><code>element-type</code> defaults to <code>character</code>, to construct a bivalent stream,
capable of both binary and character <code>io</code> use <code>:default</code>.
</p>
<p>Acceptable values for <code>buffering</code> are <code>:full</code>, <code>:line</code> and <code>:none</code>, default
is <code>:full</code>, ie. output is buffered till it is explicitly flushed using
<code>close</code> or <code>finish-output</code>. (<code>force-output</code> forces some output to be
flushed: to ensure all buffered output is flused use <code>finish-output</code>.)
</p>
<p>Streams have no <code>timeout</code> by default. If one is provided, it is the
number of seconds the system will at most wait for input to appear on
the socket stream when trying to read from it.
</p>
<p>If <code>auto-close</code> is true, the underlying <code>os</code> socket is automatically
closed after the stream and the socket have been garbage collected.
Default is false.
</p>
<p>If <code>serve-events</code> is true, blocking <code>io</code> on the socket will dispatch to
the recursive event loop. Default is false.
</p>
<p>The stream for <code>socket</code> 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).
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asocket_002derror"></a><dl>
<dt><a name="index-socket_002derror"></a>Function: <strong>socket-error</strong> <em>[sb-bsd-sockets] where &amp;optional errno</em></dt>
</dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003anon_002dblocking_002dmode"></a><dl>
<dt><a name="index-non_002dblocking_002dmode"></a>Generic Function: <strong>non-blocking-mode</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Is <code>socket</code> in non-blocking mode?
</p></dd></dl>

<hr>
<a name="Socket-Options"></a>
<div class="header">
<p>
Next: <a href="#INET-Domain-Sockets" accesskey="n" rel="next">INET Domain Sockets</a>, Previous: <a href="#General-Sockets" accesskey="p" rel="prev">General Sockets</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Socket-Options-1"></a>
<h3 class="section">14.3 Socket Options</h3>

<p>A subset of socket options are supported, using a fairly general
framework which should make it simple to add more as required - see
<samp>SYS:CONTRIB;SB-BSD-SOCKETS:SOCKOPT.LISP</samp> for details. The name
mapping from C is fairly straightforward: <code>SO_RCVLOWAT</code> becomes
<code>sockopt-receive-low-water</code> and <code>(setf
sockopt-receive-low-water)</code>.
</p>
<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dreuse_002daddress"></a><dl>
<dt><a name="index-sockopt_002dreuse_002daddress"></a>Function: <strong>sockopt-reuse-address</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-reuseaddr</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dkeep_002dalive"></a><dl>
<dt><a name="index-sockopt_002dkeep_002dalive"></a>Function: <strong>sockopt-keep-alive</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-keepalive</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002doob_002dinline"></a><dl>
<dt><a name="index-sockopt_002doob_002dinline"></a>Function: <strong>sockopt-oob-inline</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-oobinline</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dbsd_002dcompatible"></a><dl>
<dt><a name="index-sockopt_002dbsd_002dcompatible"></a>Function: <strong>sockopt-bsd-compatible</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-bsdcompat</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. Available only on Linux.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dpass_002dcredentials"></a><dl>
<dt><a name="index-sockopt_002dpass_002dcredentials"></a>Function: <strong>sockopt-pass-credentials</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-passcred</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. Available only on Linux.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002ddebug"></a><dl>
<dt><a name="index-sockopt_002ddebug"></a>Function: <strong>sockopt-debug</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-debug</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002ddont_002droute"></a><dl>
<dt><a name="index-sockopt_002ddont_002droute"></a>Function: <strong>sockopt-dont-route</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-dontroute</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dbroadcast"></a><dl>
<dt><a name="index-sockopt_002dbroadcast"></a>Function: <strong>sockopt-broadcast</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>so-broadcast</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003asockopt_002dtcp_002dnodelay"></a><dl>
<dt><a name="index-sockopt_002dtcp_002dnodelay"></a>Function: <strong>sockopt-tcp-nodelay</strong> <em>[sb-bsd-sockets] socket</em></dt>
<dd><p>Return the value of the <code>tcp-nodelay</code> socket option for <code>socket</code>. This can also be
updated with <code>setf</code>. 
</p></dd></dl>

<hr>
<a name="INET-Domain-Sockets"></a>
<div class="header">
<p>
Next: <a href="#Local-_0028Unix_0029-Domain-Sockets" accesskey="n" rel="next">Local (Unix) Domain Sockets</a>, Previous: <a href="#Socket-Options" accesskey="p" rel="prev">Socket Options</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="INET-Domain-Sockets-1"></a>
<h3 class="section">14.4 INET Domain Sockets</h3>

<p>The TCP and UDP sockets that you know and love. Some representation
issues:
</p>
<ul>
<li> IPv4 Internet addresses are represented by vectors of
<code>(unsigned-byte 8)</code> - viz. <code>#(127 0 0 1)</code>. Ports are just
integers: 6010. No conversion between network- and host-order data is
needed from the user of this package.

</li><li> IPv6 Internet addresses are represented by vectors of 16
<code>(unsigned-byte 8)</code> - viz. <code>#(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
1)</code>. Ports are just integers. As for IPv4 addresses, no conversion
between network- and host-order data is needed from the user of this
package.

</li><li> Socket addresses are represented by the two values for address and port,
so for example, <code>(socket-connect socket #(192 168 1 1) 80)</code> for
IPv4 and <code>(socket-connect socket #(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1)
80)</code> for IPv6.

</li></ul>

<a name="Class-sb_002dbsd_002dsockets_003ainet_002dsocket"></a><dl>
<dt><a name="index-inet_002dsocket"></a>Class: <strong>inet-socket</strong> <em>[sb-bsd-sockets]</em></dt>
<dd><p>Class precedence list: <code>inet-socket, socket, standard-object, t</code>
</p>
<p>Class representing <code>tcp</code> and <code>udp</code> over IPv4 sockets.
</p>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp"> (make-instance 'sb-bsd-sockets:inet-socket :type :stream :protocol :tcp)

 (make-instance 'sb-bsd-sockets:inet-socket :type :datagram :protocol :udp)
</pre></div>
</dd></dl>

<a name="Class-sb_002dbsd_002dsockets_003ainet6_002dsocket"></a><dl>
<dt><a name="index-inet6_002dsocket"></a>Class: <strong>inet6-socket</strong> <em>[sb-bsd-sockets]</em></dt>
<dd><p>Class precedence list: <code>inet6-socket, socket, standard-object, t</code>
</p>
<p>Class representing <code>tcp</code> and <code>udp</code> over IPv6 sockets.
</p>
<p>Examples:
</p>
<div class="lisp">
<pre class="lisp"> (make-instance 'sb-bsd-sockets:inet6-socket :type :stream :protocol :tcp)

 (make-instance 'sb-bsd-sockets:inet6-socket :type :datagram :protocol :udp)
</pre></div>
</dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003amake_002dinet_002daddress"></a><dl>
<dt><a name="index-make_002dinet_002daddress"></a>Function: <strong>make-inet-address</strong> <em>[sb-bsd-sockets] dotted-quads</em></dt>
<dd><p>Return a vector of octets given a string <code>dotted-quads</code> in the format
&quot;127.0.0.1&quot;. Signals an error if the string is malformed.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003amake_002dinet6_002daddress"></a><dl>
<dt><a name="index-make_002dinet6_002daddress"></a>Function: <strong>make-inet6-address</strong> <em>[sb-bsd-sockets] colon-separated-integers</em></dt>
<dd><p>Return a vector of octets given a string representation of an IPv6
address <code>colon-separated-integers</code>. Signal an error if the string is
malformed.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003aget_002dprotocol_002dby_002dname"></a><dl>
<dt><a name="index-get_002dprotocol_002dby_002dname"></a>Function: <strong>get-protocol-by-name</strong> <em>[sb-bsd-sockets] name</em></dt>
<dd><p>Given a protocol name, return the protocol number, the protocol name, and
a list of protocol aliases
</p></dd></dl>

<hr>
<a name="Local-_0028Unix_0029-Domain-Sockets"></a>
<div class="header">
<p>
Next: <a href="#Name-Service" accesskey="n" rel="next">Name Service</a>, Previous: <a href="#INET-Domain-Sockets" accesskey="p" rel="prev">INET Domain Sockets</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Local-_0028Unix_0029-Domain-Sockets-1"></a>
<h3 class="section">14.5 Local (Unix) Domain Sockets</h3>

<p>Local domain (<code>AF_LOCAL</code>) 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.
</p>
<p>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.
</p>
<a name="Class-sb_002dbsd_002dsockets_003alocal_002dsocket"></a><dl>
<dt><a name="index-local_002dsocket"></a>Class: <strong>local-socket</strong> <em>[sb-bsd-sockets]</em></dt>
<dd><p>Class precedence list: <code>local-socket, socket, standard-object, t</code>
</p>
<p>Class representing local domain (AF_LOCAL) sockets,
also known as unix-domain sockets.
</p></dd></dl>

<hr>
<a name="Name-Service"></a>
<div class="header">
<p>
Previous: <a href="#Local-_0028Unix_0029-Domain-Sockets" accesskey="p" rel="prev">Local (Unix) Domain Sockets</a>, Up: <a href="#Networking" accesskey="u" rel="up">Networking</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Name-Service-1"></a>
<h3 class="section">14.6 Name Service</h3>

<p>Presently name service is implemented by calling out to the
<code>getaddrinfo(3)</code> and <code>gethostinfo(3)</code>, or to
<code>gethostbyname(3)</code> <code>gethostbyaddr(3)</code> 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.
</p>

<a name="Class-sb_002dbsd_002dsockets_003ahost_002dent"></a><dl>
<dt><a name="index-host_002dent"></a>Class: <strong>host-ent</strong> <em>[sb-bsd-sockets]</em></dt>
<dd><p>Class precedence list: <code>host-ent, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>name</code> &mdash; initarg: <code>:name<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-bsd-sockets:host-ent-name</span><!-- /@w --></code>

<p>The name of the host
</p></li><li> <code>addresses</code> &mdash; initarg: <code>:addresses<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-bsd-sockets:host-ent-addresses</span><!-- /@w --></code>

<p>A list of addresses for this host.
</p></li></ul>

<p>This class represents the results of an address lookup.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003aget_002dhost_002dby_002dname"></a><dl>
<dt><a name="index-get_002dhost_002dby_002dname"></a>Function: <strong>get-host-by-name</strong> <em>[sb-bsd-sockets] node</em></dt>
<dd><p>Returns a <code>host-ent</code> instance for <code>node</code> or signals a <code>name-service-error</code>.
</p>
<p>Another <code>host-ent</code> instance containing zero, one or more IPv6 addresses
may be returned as a second return value.
</p>
<p><code>node</code> may also be an <code>ip</code> address in dotted quad notation or some other
weird stuff <code>-</code> see getaddrinfo(3) for the details.
</p></dd></dl>

<a name="Function-sb_002dbsd_002dsockets_003aget_002dhost_002dby_002daddress"></a><dl>
<dt><a name="index-get_002dhost_002dby_002daddress"></a>Function: <strong>get-host-by-address</strong> <em>[sb-bsd-sockets] address</em></dt>
<dd><p>Returns a <code>host-ent</code> instance for <code>address</code>, which should be a vector of
(integer 0 255) with 4 elements in case of an IPv4 address and 16
elements in case of an IPv6 address, or signals a <code>name-service-error</code>.
See gethostbyaddr(3) for details.
</p></dd></dl>

<a name="Generic_002dFunction-sb_002dbsd_002dsockets_003ahost_002dent_002daddress"></a><dl>
<dt><a name="index-host_002dent_002daddress"></a>Generic Function: <strong>host-ent-address</strong> <em>[sb-bsd-sockets] host-ent</em></dt>
<dd><p>Return some valid address for <code>host-ent</code>.
</p></dd></dl>
<hr>
<a name="Profiling"></a>
<div class="header">
<p>
Next: <a href="#Contributed-Modules" accesskey="n" rel="next">Contributed Modules</a>, Previous: <a href="#Networking" accesskey="p" rel="prev">Networking</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Profiling-1"></a>
<h2 class="chapter">15 Profiling</h2>
<a name="index-Profiling"></a>

<p>SBCL includes both a deterministic profiler, that can collect statistics
on individual functions, and a more &ldquo;modern&rdquo; statistical profiler.
</p>
<p>Inlined functions do not appear in the results reported by either.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Deterministic-Profiler" accesskey="1">Deterministic Profiler</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Statistical-Profiler" accesskey="2">Statistical Profiler</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Deterministic-Profiler"></a>
<div class="header">
<p>
Next: <a href="#Statistical-Profiler" accesskey="n" rel="next">Statistical Profiler</a>, Up: <a href="#Profiling" accesskey="u" rel="up">Profiling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deterministic-Profiler-1"></a>
<h3 class="section">15.1 Deterministic Profiler</h3>
<a name="index-Profiling_002c-deterministic"></a>

<p>The package <code>sb-profile</code> provides a classic, per-function-call
profiler.
</p>
<blockquote>
<p><b>note:</b> When profiling code executed by multiple threads in parallel, the
consing attributed to each function is inaccurate.
</p></blockquote>

<a name="Macro-sb_002dprofile_003aprofile"></a><dl>
<dt><a name="index-profile"></a>Macro: <strong>profile</strong> <em>[sb-profile] &amp;rest names</em></dt>
<dd><p><code>profile</code> Name*
</p>
<p>If no names are supplied, return the list of profiled functions.
</p>
<p>If names are supplied, wrap profiling code around the named functions.
   As in <code>trace</code>, 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
   <code>unprofile</code>, <code>report</code> and <code>reset</code>.
</p></dd></dl>
<a name="Macro-sb_002dprofile_003aunprofile"></a><dl>
<dt><a name="index-unprofile"></a>Macro: <strong>unprofile</strong> <em>[sb-profile] &amp;rest names</em></dt>
<dd><p>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. <code>names</code> defaults to the list of names of all currently
  profiled functions.
</p></dd></dl>
<a name="Function-sb_002dprofile_003areport"></a><dl>
<dt><a name="index-report"></a>Function: <strong>report</strong> <em>[sb-profile] &amp;key limit print-no-call-list</em></dt>
<dd><p>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.
</p>
<p>If <code>limit</code> is set to an integer, only the top <code>limit</code> results are
reported. If <code>print-no-call-list</code> is <code>t</code> (the default) then a list of
uncalled profiled functions are listed.
</p></dd></dl>
<a name="Function-sb_002dprofile_003areset"></a><dl>
<dt><a name="index-reset"></a>Function: <strong>reset</strong> <em>[sb-profile]</em></dt>
<dd><p>Reset the counters for all profiled functions.
</p></dd></dl>

<hr>
<a name="Statistical-Profiler"></a>
<div class="header">
<p>
Previous: <a href="#Deterministic-Profiler" accesskey="p" rel="prev">Deterministic Profiler</a>, Up: <a href="#Profiling" accesskey="u" rel="up">Profiling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Statistical-Profiler-1"></a>
<h3 class="section">15.2 Statistical Profiler</h3>
<a name="index-Profiling_002c-statistical"></a>

<p>The <code>sb-sprof</code> module, loadable by
</p><div class="lisp">
<pre class="lisp">(require :sb-sprof)
</pre></div>
<p>provides an alternate profiler which works by taking samples of the
program execution at regular intervals, instead of instrumenting
functions like <code>sb-profile:profile</code> does. You might find
<code>sb-sprof</code> more useful than the deterministic profiler when profiling
functions in the <code>common-lisp</code>-package, SBCL internals, or code
where the instrumenting overhead is excessive.
</p>
<p>Additionally <code>sb-sprof</code> includes a limited deterministic profiler
which can be used for reporting the amounts of calls to some functions
during
</p>
<a name="Example-Usage"></a>
<h4 class="subsection">15.2.1 Example Usage</h4>

<div class="lisp">
<pre class="lisp">(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 &quot;CL-USER&quot;)

;;; 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 (&amp;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))
</pre></div>

<a name="Output"></a>
<h4 class="subsection">15.2.2 Output</h4>

<p>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.
</p>
<div class="lisp">
<pre class="lisp">           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
</pre></div>

<p>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.
</p>
<p>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 <code>profile-call-counts</code>.
</p>
<p>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.
</p>
<div class="lisp">
<pre class="lisp">;      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
</pre></div>

<a name="Platform-support"></a>
<h4 class="subsection">15.2.3 Platform support</h4>

<p>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.
</p>
<p>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.
</p>
<a name="Macros"></a>
<h4 class="subsection">15.2.4 Macros</h4>

<a name="Macro-sb_002dsprof_003awith_002dprofiling"></a><dl>
<dt><a name="index-with_002dprofiling"></a>Macro: <strong>with-profiling</strong> <em>[sb-sprof] (&amp;key sample-interval alloc-interval max-samples reset mode loop max-depth show-progress threads report) &amp;body body</em></dt>
<dd><p>Evaluate <code>body</code> with statistical profiling turned on. If <code>loop</code> is true,
loop around the <code>body</code> until a sufficient number of samples has been collected.
Returns the values from the last evaluation of <code>body</code>.
</p>
<p>In multithreaded operation, only the thread in which <code>with-profiling</code> was
evaluated will be profiled by default. If you want to profile multiple
threads, invoke the profiler with <code>start-profiling</code>.
</p>
<p>The following keyword args are recognized:
</p>

<dl compact="compact">
<dt><em><code>:sample-interval</code> &lt;n&gt;</em></dt>
<dd><p>Take a sample every &lt;n&gt; seconds. Default is <code>*sample-interval*</code>.
</p>

</dd>
<dt><em><code>:alloc-interval</code> &lt;n&gt;</em></dt>
<dd><p>Take a sample every time &lt;n&gt; allocation regions (approximately
   8kB) have been allocated since the last sample. Default is
   <code>*alloc-interval*</code>.
</p>

</dd>
<dt><em><code>:mode</code> &lt;mode&gt;</em></dt>
<dd><p>If <code>:cpu</code>, run the profiler in <code>cpu</code> profiling mode. If <code>:alloc</code>, run the
   profiler in allocation profiling mode. If <code>:time</code>, run the profiler
   in wallclock profiling mode.
</p>

</dd>
<dt><em><code>:max-samples</code> &lt;max&gt;</em></dt>
<dd><p>Repeat evaluating body until &lt;max&gt; samples are taken.
   Default is <code>*max-samples*</code>.
</p>

</dd>
<dt><em><code>:max-depth</code> &lt;max&gt;</em></dt>
<dd><p>Maximum call stack depth that the profiler should consider. Only
   has an effect on x86 and x86-64.
</p>

</dd>
<dt><em><code>:report</code> &lt;type&gt;</em></dt>
<dd><p>If specified, call <code>report</code> with <code>:type</code> &lt;type&gt; at the end.
</p>

</dd>
<dt><em><code>:reset</code> &lt;bool&gt;</em></dt>
<dd><p>It true, call <code>reset</code> at the beginning.
</p>

</dd>
<dt><em><code>:threads</code> &lt;list-form&gt;</em></dt>
<dd><p>Form that evaluates to the list threads to profile, or <code>:all</code> to indicate
   that all threads should be profiled. Defaults to the current
   thread. (Note: <code>start-profiling</code> defaults to all threads.)
</p>
<p><code>:threads</code> has no effect on call-counting at the moment.
</p>
<p>On some platforms (eg. Darwin) the signals used by the profiler are
   not properly delivered to threads in proportion to their <code>cpu</code> usage
   when doing <code>:cpu</code> profiling. If you see empty call graphs, or are obviously
   missing several samples from certain threads, you may be falling afoul
   of this. In this case using <code>:mode</code> <code>:time</code> is likely to work better.
</p>

</dd>
<dt><em><code>:loop</code> &lt;bool&gt;</em></dt>
<dd><p>If false (the default), evaluate <code>body</code> only once. If true repeatedly
   evaluate <code>body</code>.
</p></dd>
</dl>

</dd></dl>
<a name="Macro-sb_002dsprof_003awith_002dsampling"></a><dl>
<dt><a name="index-with_002dsampling"></a>Macro: <strong>with-sampling</strong> <em>[sb-sprof] (&amp;optional on) &amp;body body</em></dt>
<dd><p>Evaluate body with statistical sampling turned on or off.
</p></dd></dl>

<a name="Functions"></a>
<h4 class="subsection">15.2.5 Functions</h4>

<a name="Function-sb_002dsprof_003areport"></a><dl>
<dt><a name="index-report-1"></a>Function: <strong>report</strong> <em>[sb-sprof] &amp;key type max min-percent call-graph sort-by sort-order stream show-progress</em></dt>
<dd><p>Report statistical profiling results.  The following keyword
   args are recognized:
</p>

<dl compact="compact">
<dt><em><code>:type</code> &lt;type&gt;</em></dt>
<dd><p>Specifies the type of report to generate.  If <code>:flat</code>, show
      flat report, if <code>:graph</code> show a call graph and a flat report.
      If nil, don&rsquo;t print out a report.
</p>

</dd>
<dt><em><code>:stream</code> &lt;stream&gt;</em></dt>
<dd><p>Specify a stream to print the report on.  Default is
      <code>*standard-output*</code>.
</p>

</dd>
<dt><em><code>:max</code> &lt;max&gt;</em></dt>
<dd><p>Don&rsquo;t show more than &lt;max&gt; entries in the flat report.
</p>

</dd>
<dt><em><code>:min-percent</code> &lt;min-percent&gt;</em></dt>
<dd><p>Don&rsquo;t show functions taking less than &lt;min-percent&gt; of the
      total time in the flat report.
</p>

</dd>
<dt><em><code>:sort-by</code> &lt;column&gt;</em></dt>
<dd><p>If <code>:samples</code>, sort flat report by number of samples taken.
      If <code>:cumulative-samples</code>, sort flat report by cumulative number of samples
      taken (shows how much time each function spent on stack.) Default
      is <code>*report-sort-by*</code>.
</p>

</dd>
<dt><em><code>:sort-order</code> &lt;order&gt;</em></dt>
<dd><p>If <code>:descending</code>, sort flat report in descending order. If <code>:ascending</code>,
      sort flat report in ascending order. Default is <code>*report-sort-order*</code>.
</p>

</dd>
<dt><em><code>:show-progress</code> &lt;bool&gt;</em></dt>
<dd><p>If true, print progress messages while generating the call graph.
</p>

</dd>
<dt><em><code>:call-graph</code> &lt;graph&gt;</em></dt>
<dd><p>Print a report from &lt;graph&gt; instead of the latest profiling
     results.
</p>
</dd>
</dl>

<p>Value of this function is a <code>call-graph</code> object representing the
resulting call-graph, or <code>nil</code> if there are no samples (eg. right after
calling <code>reset</code>.)
</p>
<p>Profiling is stopped before the call graph is generated.
</p></dd></dl>

<a name="Function-sb_002dsprof_003areset"></a><dl>
<dt><a name="index-reset-1"></a>Function: <strong>reset</strong> <em>[sb-sprof]</em></dt>
<dd><p>Reset the profiler.
</p></dd></dl>

<a name="Function-sb_002dsprof_003astart_002dprofiling"></a><dl>
<dt><a name="index-start_002dprofiling"></a>Function: <strong>start-profiling</strong> <em>[sb-sprof] &amp;key max-samples mode sample-interval alloc-interval max-depth threads sampling</em></dt>
<dd><p>Start profiling statistically in the current thread if not already profiling.
The following keyword args are recognized:
</p>

<dl compact="compact">
<dt><em><code>:sample-interval</code> &lt;n&gt;</em></dt>
<dd><p>Take a sample every &lt;n&gt; seconds.  Default is <code>*sample-interval*</code>.
</p>

</dd>
<dt><em><code>:alloc-interval</code> &lt;n&gt;</em></dt>
<dd><p>Take a sample every time &lt;n&gt; allocation regions (approximately
     8kB) have been allocated since the last sample. Default is
     <code>*alloc-interval*</code>.
</p>

</dd>
<dt><em><code>:mode</code> &lt;mode&gt;</em></dt>
<dd><p>If <code>:cpu</code>, run the profiler in <code>cpu</code> profiling mode. If <code>:alloc</code>, run
     the profiler in allocation profiling mode. If <code>:time</code>, run the profiler
     in wallclock profiling mode.
</p>

</dd>
<dt><em><code>:max-samples</code> &lt;max&gt;</em></dt>
<dd><p>Maximum number of samples.  Default is <code>*max-samples*</code>.
</p>

</dd>
<dt><em><code>:max-depth</code> &lt;max&gt;</em></dt>
<dd><p>Maximum call stack depth that the profiler should consider. Only
     has an effect on x86 and x86-64.
</p>

</dd>
<dt><em><code>:threads</code> &lt;list&gt;</em></dt>
<dd><p>List threads to profile, or <code>:all</code> to indicate that all threads should be
     profiled. Defaults to <code>:all</code>. (Note: <code>with-profiling</code> defaults to the current
     thread.)
</p>
<p><code>:threads</code> has no effect on call-counting at the moment.
</p>
<p>On some platforms (eg. Darwin) the signals used by the profiler are
     not properly delivered to threads in proportion to their <code>cpu</code> usage
     when doing <code>:cpu</code> profiling. If you see empty call graphs, or are obviously
     missing several samples from certain threads, you may be falling afoul
     of this.
</p>

</dd>
<dt><em><code>:sampling</code> &lt;bool&gt;</em></dt>
<dd><p>If true, the default, start sampling right away.
     If false, <code>start-sampling</code> can be used to turn sampling on.
</p></dd>
</dl>

</dd></dl>

<a name="Function-sb_002dsprof_003astop_002dprofiling"></a><dl>
<dt><a name="index-stop_002dprofiling"></a>Function: <strong>stop-profiling</strong> <em>[sb-sprof]</em></dt>
<dd><p>Stop profiling if profiling.
</p></dd></dl>

<a name="Function-sb_002dsprof_003aprofile_002dcall_002dcounts"></a><dl>
<dt><a name="index-profile_002dcall_002dcounts"></a>Function: <strong>profile-call-counts</strong> <em>[sb-sprof] &amp;rest names</em></dt>
<dd><p>Mark the functions named by <code>names</code> 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 <code>x</code> or <code>(setf x)</code>, where <code>x</code> is a symbol
with the package as its home package.
</p></dd></dl>

<a name="Function-sb_002dsprof_003aunprofile_002dcall_002dcounts"></a><dl>
<dt><a name="index-unprofile_002dcall_002dcounts"></a>Function: <strong>unprofile-call-counts</strong> <em>[sb-sprof]</em></dt>
<dd><p>Clear all call counting information. Call counting will be done for no
functions during statistical profiling.
</p></dd></dl>

<a name="Variables"></a>
<h4 class="subsection">15.2.6 Variables</h4>

<a name="Variable-sb_002dsprof_003a_002amax_002dsamples_002a"></a><dl>
<dt><a name="index-_002amax_002dsamples_002a"></a>Variable: <strong>*max-samples*</strong> <em>[sb-sprof]</em></dt>
<dd><p>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.
</p></dd></dl>

<a name="Variable-sb_002dsprof_003a_002asample_002dinterval_002a"></a><dl>
<dt><a name="index-_002asample_002dinterval_002a"></a>Variable: <strong>*sample-interval*</strong> <em>[sb-sprof]</em></dt>
<dd><p>Default number of seconds between samples.
</p></dd></dl>

<a name="Credits"></a>
<h4 class="subsection">15.2.7 Credits</h4>

<p><code>sb-sprof</code> is an SBCL port, with enhancements, of Gerd
Moellmann&rsquo;s statistical profiler for CMUCL.
</p><hr>
<a name="Contributed-Modules"></a>
<div class="header">
<p>
Next: <a href="#Deprecation" accesskey="n" rel="next">Deprecation</a>, Previous: <a href="#Profiling" accesskey="p" rel="prev">Profiling</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Contributed-Modules-1"></a>
<h2 class="chapter">16 Contributed Modules</h2>

<p>SBCL comes with a number of modules that are not part of the core
system.  These are loaded via <code>(require :<var>modulename</var>)</code>
(see <a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a>).  This section contains
documentation (or pointers to documentation) for some of the
contributed modules.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#sb_002daclrepl" accesskey="1">sb-aclrepl</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dconcurrency" accesskey="2">sb-concurrency</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dcover" accesskey="3">sb-cover</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dgrovel" accesskey="4">sb-grovel</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dmd5" accesskey="5">sb-md5</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dposix" accesskey="6">sb-posix</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002dqueue" accesskey="7">sb-queue</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#sb_002drotate_002dbyte" accesskey="8">sb-rotate-byte</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="sb_002daclrepl"></a>
<div class="header">
<p>
Next: <a href="#sb_002dconcurrency" accesskey="n" rel="next">sb-concurrency</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002daclrepl-1"></a>
<h3 class="section">16.1 sb-aclrepl</h3>
<a name="index-Read_002dEval_002dPrint-Loop"></a>
<a name="index-REPL"></a>

<p>The <code>sb-aclrepl</code> module offers an Allegro CL-style
Read-Eval-Print Loop for SBCL, with integrated inspector.  Adding a
debugger interface is planned.
</p>
<a name="Usage"></a>
<h4 class="subsection">16.1.1 Usage</h4>

<p>To start <code>sb-aclrepl</code> as your read-eval-print loop, put the form
</p><div class="lisp">
<pre class="lisp">(require 'sb-aclrepl)
</pre></div>

<p>in your <samp>~/.sbclrc</samp> initialization file.
</p>
<a name="Example-Initialization"></a>
<h4 class="subsection">16.1.2 Example Initialization</h4>

<p>Here&rsquo;s a longer example of a <samp>~/.sbclrc</samp> file that shows off
some of the features of <code>sb-aclrepl</code>:
</p>
<div class="lisp">
<pre class="lisp">(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 &quot;asdc&quot;)
       #'(lambda (sys) (asdf:operate 'asdf:compile-op sys)))
  (sb-aclrepl:alias &quot;l&quot; (sys) (asdf:operate 'asdf:load-op sys))
  (sb-aclrepl:alias &quot;t&quot; (sys) (asdf:operate 'asdf:test-op sys))
  ;; The 1 below means that two characaters (&quot;up&quot;) are required
  (sb-aclrepl:alias (&quot;up&quot; 1 &quot;Use package&quot;) (package) (use-package package))
  ;; The 0 below means only the first letter (&quot;r&quot;) is required,
  ;; such as &quot;:r base64&quot;
  (sb-aclrepl:alias (&quot;require&quot; 0 &quot;Require module&quot;) (sys) (require sys))
  (setq cl:*features* (delete :aclrepl cl:*features*)))
</pre></div>

<p>Questions, comments, or bug reports should be sent to Kevin Rosenberg
(<a href="mailto:kevin@rosenberg.net">kevin@rosenberg.net</a>).
</p>
<a name="Credits-1"></a>
<h4 class="subsection">16.1.3 Credits</h4>

<p>Allegro CL is a registered trademark of Franz Inc.
</p>
<hr>
<a name="sb_002dconcurrency"></a>
<div class="header">
<p>
Next: <a href="#sb_002dcover" accesskey="n" rel="next">sb-cover</a>, Previous: <a href="#sb_002daclrepl" accesskey="p" rel="prev">sb-aclrepl</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dconcurrency-1"></a>
<h3 class="section">16.2 sb-concurrency</h3>
<a name="index-Concurrency"></a>
<a name="index-Sb_002dconcurrency"></a>

<p>Additional data structures, synchronization primitives and tools for
concurrent programming. Similiar to Java&rsquo;s <code>java.util.concurrent</code>
package.
</p>
<a name="Section-sb_002dconcurrency_003aqueue"></a><a name="Queue"></a>
<h4 class="subsection">16.2.1 Queue</h4>
<a name="index-Queue_002c-lock_002dfree"></a>

<p><code>sb-concurrency:queue</code> is a lock-free, thread-safe FIFO queue
datatype.
<br><br>
The implementation is based on <cite>An Optimistic Approach to
Lock-Free FIFO Queues</cite> by Edya Ladan-Mozes and Nir Shavit.
<br><br>
Before SBCL 1.0.38, this implementation resided in its own contrib
(see <a href="#sb_002dqueue">sb-queue</a>) which is still provided for backwards-compatibility
but which has since been deprecated.
</p>
<a name="Structure-sb_002dconcurrency_003aqueue"></a><dl>
<dt><a name="index-queue"></a>Structure: <strong>queue</strong> <em>[sb-concurrency]</em></dt>
<dd><p>Class precedence list: <code>queue, structure-object, t</code>
</p>
<p>Lock-free thread safe <code>fifo</code> queue.
</p>
<p>Use <code>enqueue</code> to add objects to the queue, and <code>dequeue</code> to remove them.
</p></dd></dl>

<a name="Function-sb_002dconcurrency_003adequeue"></a><dl>
<dt><a name="index-dequeue"></a>Function: <strong>dequeue</strong> <em>[sb-concurrency] queue</em></dt>
<dd><p>Retrieves the oldest value in <code>queue</code> and returns it as the primary value,
and <code>t</code> as secondary value. If the queue is empty, returns <code>nil</code> as both primary
and secondary value.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aenqueue"></a><dl>
<dt><a name="index-enqueue"></a>Function: <strong>enqueue</strong> <em>[sb-concurrency] value queue</em></dt>
<dd><p>Adds <code>value</code> to the end of <code>queue</code>. Returns <code>value</code>.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003alist_002dqueue_002dcontents"></a><dl>
<dt><a name="index-list_002dqueue_002dcontents"></a>Function: <strong>list-queue-contents</strong> <em>[sb-concurrency] queue</em></dt>
<dd><p>Returns the contents of <code>queue</code> as a list without removing them from the
<code>queue</code>. Mainly useful for manual examination of queue state, as the list may be
out of date by the time it is returned, and concurrent dequeue operations may
in the worse case force the queue-traversal to be restarted several times.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amake_002dqueue"></a><dl>
<dt><a name="index-make_002dqueue"></a>Function: <strong>make-queue</strong> <em>[sb-concurrency] &amp;key name initial-contents</em></dt>
<dd><p>Returns a new <code>queue</code> with <code>name</code> and contents of the <code>initial-contents</code>
sequence enqueued.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aqueue_002dcount"></a><dl>
<dt><a name="index-queue_002dcount"></a>Function: <strong>queue-count</strong> <em>[sb-concurrency] queue</em></dt>
<dd><p>Returns the number of objects in <code>queue</code>. Mainly useful for manual
examination of queue state, and in <code>print-object</code> methods: inefficient as it
must walk the entire queue.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aqueue_002dempty_002dp"></a><dl>
<dt><a name="index-queue_002dempty_002dp"></a>Function: <strong>queue-empty-p</strong> <em>[sb-concurrency] queue</em></dt>
<dd><p>Returns <code>t</code> if <code>queue</code> is empty, <code>nil</code> otherwise.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aqueue_002dname"></a><dl>
<dt><a name="index-queue_002dname"></a>Function: <strong>queue-name</strong> <em>[sb-concurrency] instance</em></dt>
<dd><p>Name of a <code>queue</code>. Can be assigned to using <code>setf</code>. Queue names
can be arbitrary printable objects, and need not be unique.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aqueuep"></a><dl>
<dt><a name="index-queuep"></a>Function: <strong>queuep</strong> <em>[sb-concurrency] object</em></dt>
<dd><p>Returns true if argument is a <code>queue</code>, <code>nil</code> otherwise.
</p></dd></dl>

<a name="Mailbox-_0028lock_002dfree_0029"></a>
<h4 class="subsection">16.2.2 Mailbox (lock-free)</h4>
<a name="index-Mailbox_002c-lock_002dfree"></a>

<p><code>sb-concurrency:mailbox</code> is a lock-free message queue where one
or multiple ends can send messages to one or multiple receivers. The
difference to <a href="#Section-sb_002dconcurrency_003aqueue">queues</a> is that the receiving
end may block until a message arrives.
<br><br>
Built on top of the <a href="#Structure-sb_002dconcurrency_003aqueue">queue</a> implementation.
</p>
<a name="Structure-sb_002dconcurrency_003amailbox"></a><dl>
<dt><a name="index-mailbox"></a>Structure: <strong>mailbox</strong> <em>[sb-concurrency]</em></dt>
<dd><p>Class precedence list: <code>mailbox, structure-object, t</code>
</p>
<p>Mailbox aka message queue.
</p>
<p><code>send-message</code> adds a message to the mailbox, <code>receive-message</code> waits till
a message becomes available, whereas <code>receive-message-no-hang</code> is a non-blocking
variant, and <code>receive-pending-messages</code> empties the entire mailbox in one go.
</p>
<p>Messages can be arbitrary objects
</p></dd></dl>

<a name="Function-sb_002dconcurrency_003alist_002dmailbox_002dmessages"></a><dl>
<dt><a name="index-list_002dmailbox_002dmessages"></a>Function: <strong>list-mailbox-messages</strong> <em>[sb-concurrency] mailbox</em></dt>
<dd><p>Returns a fresh list containing all the messages in the
mailbox. Does not remove messages from the mailbox.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amailbox_002dcount"></a><dl>
<dt><a name="index-mailbox_002dcount"></a>Function: <strong>mailbox-count</strong> <em>[sb-concurrency] mailbox</em></dt>
<dd><p>Returns the number of messages currently in the mailbox.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amailbox_002dempty_002dp"></a><dl>
<dt><a name="index-mailbox_002dempty_002dp"></a>Function: <strong>mailbox-empty-p</strong> <em>[sb-concurrency] mailbox</em></dt>
<dd><p>Returns true if <code>mailbox</code> is currently empty, <code>nil</code> otherwise.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amailbox_002dname"></a><dl>
<dt><a name="index-mailbox_002dname"></a>Function: <strong>mailbox-name</strong> <em>[sb-concurrency] instance</em></dt>
<dd><p>Name of a <code>mailbox</code>. SETFable.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amailboxp"></a><dl>
<dt><a name="index-mailboxp"></a>Function: <strong>mailboxp</strong> <em>[sb-concurrency] object</em></dt>
<dd><p>Returns true if argument is a <code>mailbox</code>, <code>nil</code> otherwise.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amake_002dmailbox"></a><dl>
<dt><a name="index-make_002dmailbox"></a>Function: <strong>make-mailbox</strong> <em>[sb-concurrency] &amp;key name initial-contents</em></dt>
<dd><p>Returns a new <code>mailbox</code> with messages in <code>initial-contents</code> enqueued.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003areceive_002dmessage"></a><dl>
<dt><a name="index-receive_002dmessage"></a>Function: <strong>receive-message</strong> <em>[sb-concurrency] mailbox &amp;key timeout</em></dt>
<dd><p>Removes the oldest message from <code>mailbox</code> and returns it as the primary
value, and a secondary value of <code>t</code>. If <code>mailbox</code> is empty waits until a message
arrives.
</p>
<p>If <code>timeout</code> is provided, and no message arrives within the specified interval,
returns primary and secondary value of <code>nil</code>.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003areceive_002dmessage_002dno_002dhang"></a><dl>
<dt><a name="index-receive_002dmessage_002dno_002dhang"></a>Function: <strong>receive-message-no-hang</strong> <em>[sb-concurrency] mailbox</em></dt>
<dd><p>The non-blocking variant of <code>receive-message</code>. Returns two values,
the message removed from <code>mailbox</code>, and a flag specifying whether a
message could be received.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003areceive_002dpending_002dmessages"></a><dl>
<dt><a name="index-receive_002dpending_002dmessages"></a>Function: <strong>receive-pending-messages</strong> <em>[sb-concurrency] mailbox &amp;optional n</em></dt>
<dd><p>Removes and returns all (or at most N) currently pending messages
from <code>mailbox</code>, or returns <code>nil</code> if no messages are pending.
</p>
<p>Note: Concurrent threads may be snarfing messages during the run of
this function, so even though <code>x</code>,<code>y</code> appear right next to each other in
the result, does not necessarily mean that <code>y</code> was the message sent
right after <code>x</code>.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003asend_002dmessage"></a><dl>
<dt><a name="index-send_002dmessage"></a>Function: <strong>send-message</strong> <em>[sb-concurrency] mailbox message</em></dt>
<dd><p>Adds a <code>message</code> to <code>mailbox</code>. Message can be any object.
</p></dd></dl>

<a name="Section-sb_002dconcurrency_003agate"></a><a name="Gates"></a>
<h4 class="subsection">16.2.3 Gates</h4>
<a name="index-Gate"></a>

<p><code>sb-concurrency:gate</code> is a synchronization object suitable for when
multiple threads must wait for a single event before proceeding.
</p>
<a name="Structure-sb_002dconcurrency_003agate"></a><dl>
<dt><a name="index-gate"></a>Structure: <strong>gate</strong> <em>[sb-concurrency]</em></dt>
<dd><p>Class precedence list: <code>gate, structure-object, t</code>
</p>
<p><code>gate</code> type. Gates are synchronization constructs suitable for making
multiple threads wait for single event before proceeding.
</p>
<p>Use <code>wait-on-gate</code> to wait for a gate to open, <code>open-gate</code> to open one,
and <code>close-gate</code> to close an open gate. <code>gate-open-p</code> can be used to test
the state of a gate without blocking.
</p></dd></dl>

<a name="Function-sb_002dconcurrency_003aclose_002dgate"></a><dl>
<dt><a name="index-close_002dgate"></a>Function: <strong>close-gate</strong> <em>[sb-concurrency] gate</em></dt>
<dd><p>Closes <code>gate</code>. Returns <code>t</code> if the gate was previously open, and <code>nil</code>
if the gate was already closed.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003agate_002dname"></a><dl>
<dt><a name="index-gate_002dname"></a>Function: <strong>gate-name</strong> <em>[sb-concurrency] instance</em></dt>
<dd><p>Name of a <code>gate</code>. SETFable.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003agate_002dopen_002dp"></a><dl>
<dt><a name="index-gate_002dopen_002dp"></a>Function: <strong>gate-open-p</strong> <em>[sb-concurrency] gate</em></dt>
<dd><p>Returns true if <code>gate</code> is open.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003agatep"></a><dl>
<dt><a name="index-gatep"></a>Function: <strong>gatep</strong> <em>[sb-concurrency] object</em></dt>
<dd><p>Returns true if the argument is a <code>gate</code>.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003amake_002dgate"></a><dl>
<dt><a name="index-make_002dgate"></a>Function: <strong>make-gate</strong> <em>[sb-concurrency] &amp;key name open</em></dt>
<dd><p>Makes a new gate. Gate will be initially open if <code>open</code> is true, and closed if <code>open</code>
is <code>nil</code> (the default.) <code>name</code>, if provided, is the name of the gate, used when printing
the gate.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003aopen_002dgate"></a><dl>
<dt><a name="index-open_002dgate"></a>Function: <strong>open-gate</strong> <em>[sb-concurrency] gate</em></dt>
<dd><p>Opens <code>gate</code>. Returns <code>t</code> if the gate was previously closed, and <code>nil</code>
if the gate was already open.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003await_002don_002dgate"></a><dl>
<dt><a name="index-wait_002don_002dgate"></a>Function: <strong>wait-on-gate</strong> <em>[sb-concurrency] gate &amp;key timeout</em></dt>
<dd><p>Waits for <code>gate</code> to open, or <code>timeout</code> seconds to pass. Returns <code>t</code>
if the gate was opened in time, and <code>nil</code> otherwise.
</p></dd></dl>

<a name="Section-sb_002dconcurrency_003afrlock"></a><a name="Frlocks_002c-aka-Fast-Read-Locks"></a>
<h4 class="subsection">16.2.4 Frlocks, aka Fast Read Locks</h4>
<a name="index-Frlock"></a>
<a name="index-Fast-Read-Lock"></a>

<a name="Structure-sb_002dconcurrency_003afrlock"></a><dl>
<dt><a name="index-frlock"></a>Structure: <strong>frlock</strong> <em>[sb-concurrency]</em></dt>
<dd><p>Class precedence list: <code>frlock, structure-object, t</code>
</p>
<p>FRlock, aka Fast Read Lock.
</p>
<p>Fast Read Locks allow multiple readers and one potential writer to operate in
parallel while providing for consistency for readers and mutual exclusion for
writers.
</p>
<p>Readers gain entry to protected regions without waiting, but need to retry if
a writer operated inside the region while they were reading. This makes frlocks
very efficient when readers are much more common than writers.
</p>
<p>FRlocks are <code>not</code> suitable when it is not safe at all for readers and writers to
operate on the same data in parallel: they provide consistency, not exclusion
between readers and writers. Hence using an frlock to eg. protect an <code>sbcl</code>
hash-table is unsafe. If multiple readers operating in parallel with a writer
would be safe but inconsistent without a lock, frlocks are suitable.
</p>
<p>The recommended interface to use is <code>frlock-read</code> and <code>frlock-write</code>, but those
needing it can also use a lower-level interface.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">  ;; Values returned by FOO are always consistent so that
  ;; the third value is the sum of the two first ones.
  (let ((a 0)
        (b 0)
        (c 0)
        (lk (make-frlock)))
    (defun foo ()
       (frlock-read (lk) a b c))
    (defun bar (x y)
       (frlock-write (lk)
         (setf a x
               b y
               c (+ x y)))))
</pre></div>
</dd></dl>

<a name="Macro-sb_002dconcurrency_003afrlock_002dread"></a><dl>
<dt><a name="index-frlock_002dread"></a>Macro: <strong>frlock-read</strong> <em>[sb-concurrency] (frlock) &amp;body value-forms</em></dt>
<dd><p>Evaluates <code>value-forms</code> under <code>frlock</code> till it obtains a consistent
set, and returns that as multiple values.
</p></dd></dl>
<a name="Macro-sb_002dconcurrency_003afrlock_002dwrite"></a><dl>
<dt><a name="index-frlock_002dwrite"></a>Macro: <strong>frlock-write</strong> <em>[sb-concurrency] (frlock &amp;key wait-p timeout) &amp;body body</em></dt>
<dd><p>Executes <code>body</code> while holding <code>frlock</code> for writing.
</p></dd></dl>

<a name="Function-sb_002dconcurrency_003amake_002dfrlock"></a><dl>
<dt><a name="index-make_002dfrlock"></a>Function: <strong>make-frlock</strong> <em>[sb-concurrency] &amp;key name</em></dt>
<dd><p>Returns a new <code>frlock</code> with <code>name</code>.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003afrlock_002dname"></a><dl>
<dt><a name="index-frlock_002dname"></a>Function: <strong>frlock-name</strong> <em>[sb-concurrency] instance</em></dt>
<dd><p>Name of an <code>frlock</code>. SETFable.
</p></dd></dl>

<a name="Function-sb_002dconcurrency_003afrlock_002dread_002dbegin"></a><dl>
<dt><a name="index-frlock_002dread_002dbegin"></a>Function: <strong>frlock-read-begin</strong> <em>[sb-concurrency] frlock</em></dt>
<dd><p>Start a read sequence on <code>frlock</code>. Returns a read-token and an epoch to be
validated later.
</p>
<p>Using <code>frlock-read</code> instead is recommended.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003afrlock_002dread_002dend"></a><dl>
<dt><a name="index-frlock_002dread_002dend"></a>Function: <strong>frlock-read-end</strong> <em>[sb-concurrency] frlock</em></dt>
<dd><p>Ends a read sequence on <code>frlock</code>. Returns a token and an epoch. If the token
and epoch are <code>eql</code> to the read-token and epoch returned by <code>frlock-read-begin</code>,
the values read under the <code>frlock</code> are consistent and can be used: if the values
differ, the values are inconsistent and the read must be restated.
</p>
<p>Using <code>frlock-read</code> instead is recommended.
</p>
<p>Example:
</p>
<div class="lisp">
<pre class="lisp">  (multiple-value-bind (t0 e0) (frlock-read-begin *fr*)
    (let ((a (get-a))
          (b (get-b)))
      (multiple-value-bind (t1 e1) (frlock-read-end *fr*)
        (if (and (eql t0 t1) (eql e0 e1))
            (list :a a :b b)
            :aborted))))
</pre></div>
</dd></dl>
<a name="Function-sb_002dconcurrency_003agrab_002dfrlock_002dwrite_002dlock"></a><dl>
<dt><a name="index-grab_002dfrlock_002dwrite_002dlock"></a>Function: <strong>grab-frlock-write-lock</strong> <em>[sb-concurrency] frlock &amp;key wait-p timeout</em></dt>
<dd><p>Acquires <code>frlock</code> for writing, invalidating existing and future read-tokens
for the duration. Returns <code>t</code> on success, and <code>nil</code> if the lock wasn&rsquo;t acquired
due to eg. a timeout. Using <code>frlock-write</code> instead is recommended.
</p></dd></dl>
<a name="Function-sb_002dconcurrency_003arelease_002dfrlock_002dwrite_002dlock"></a><dl>
<dt><a name="index-release_002dfrlock_002dwrite_002dlock"></a>Function: <strong>release-frlock-write-lock</strong> <em>[sb-concurrency] frlock</em></dt>
<dd><p>Releases <code>frlock</code> after writing, allowing valid read-tokens to be acquired again.
Signals an error if the current thread doesn&rsquo;t hold <code>frlock</code> for writing. Using <code>frlock-write</code>
instead is recommended.
</p></dd></dl>

<hr>
<a name="sb_002dcover"></a>
<div class="header">
<p>
Next: <a href="#sb_002dgrovel" accesskey="n" rel="next">sb-grovel</a>, Previous: <a href="#sb_002dconcurrency" accesskey="p" rel="prev">sb-concurrency</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dcover-1"></a>
<h3 class="section">16.3 sb-cover</h3>
<a name="index-Code-Coverage"></a>

<p>The <code>sb-cover</code> 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
<code>compile-file</code> with the value of the
<code>sb-cover:store-coverage-data</code> optimization quality set to 3.
</p>
<p>As of SBCL 1.0.6 <code>sb-cover</code> is still experimental, and the
interfaces documented here might change in later versions.
</p>
<a name="Example-Usage-1"></a>
<h4 class="subsection">16.3.1 Example Usage</h4>

<div class="lisp">
<pre class="lisp">;;; 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 &quot;/tmp/report/&quot;)

;;; Turn off instrumentation
(declaim (optimize (sb-cover:store-coverage-data 0)))
</pre></div>


<a name="Functions-1"></a>
<h4 class="subsection">16.3.2 Functions</h4>

<a name="Function-sb_002dcover_003areport"></a><dl>
<dt><a name="index-report-2"></a>Function: <strong>report</strong> <em>[sb-cover] directory &amp;key form-mode external-format</em></dt>
<dd><p>Print a code coverage report of all instrumented files into <code>directory</code>.
If <code>directory</code> 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 <code>external-format</code> parameter.
</p>
<p>If the keyword argument <code>form-mode</code> has the value <code>:car</code>, the annotations in
the coverage report will be placed on the CARs of any cons-forms, while if
it has the value <code>:whole</code> 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.
</p></dd></dl>

<a name="Function-sb_002dcover_003areset_002dcoverage"></a><dl>
<dt><a name="index-reset_002dcoverage"></a>Function: <strong>reset-coverage</strong> <em>[sb-cover]</em></dt>
<dd><p>Reset all coverage data back to the &lsquo;Not executed&lsquo; state.
</p></dd></dl>

<a name="Function-sb_002dcover_003aclear_002dcoverage"></a><dl>
<dt><a name="index-clear_002dcoverage"></a>Function: <strong>clear-coverage</strong> <em>[sb-cover]</em></dt>
<dd><p>Clear all files from the coverage database. The files will be re-entered
into the database when the <code>fasl</code> files (produced by compiling
<code>store-coverage-data</code> optimization policy set to 3) are loaded again into the
image.
</p></dd></dl>

<a name="Function-sb_002dcover_003asave_002dcoverage"></a><dl>
<dt><a name="index-save_002dcoverage"></a>Function: <strong>save-coverage</strong> <em>[sb-cover]</em></dt>
<dd><p>Returns an opaque representation of the current code coverage state.
The only operation that may be done on the state is passing it to
<code>restore-coverage</code>. The representation is guaranteed to be readably printable.
A representation that has been printed and read back will work identically
in <code>restore-coverage</code>.
</p></dd></dl>

<a name="Function-sb_002dcover_003asave_002dcoverage_002din_002dfile"></a><dl>
<dt><a name="index-save_002dcoverage_002din_002dfile"></a>Function: <strong>save-coverage-in-file</strong> <em>[sb-cover] pathname</em></dt>
<dd><p>Call <code>save-coverage</code> and write the results of that operation into the
file designated by <code>pathname</code>.
</p></dd></dl>

<a name="Function-sb_002dcover_003arestore_002dcoverage"></a><dl>
<dt><a name="index-restore_002dcoverage"></a>Function: <strong>restore-coverage</strong> <em>[sb-cover] coverage-state</em></dt>
<dd><p>Restore the code coverage data back to an earlier state produced by
<code>save-coverage</code>.
</p></dd></dl>

<a name="Function-sb_002dcover_003arestore_002dcoverage_002dfrom_002dfile"></a><dl>
<dt><a name="index-restore_002dcoverage_002dfrom_002dfile"></a>Function: <strong>restore-coverage-from-file</strong> <em>[sb-cover] pathname</em></dt>
<dd><p><code>read</code> the contents of the file designated by <code>pathname</code> and pass the
result to <code>restore-coverage</code>.
</p></dd></dl>


<hr>
<a name="sb_002dgrovel"></a>
<div class="header">
<p>
Next: <a href="#sb_002dmd5" accesskey="n" rel="next">sb-md5</a>, Previous: <a href="#sb_002dcover" accesskey="p" rel="prev">sb-cover</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dgrovel-1"></a>
<h3 class="section">16.4 sb-grovel</h3>
<a name="index-Foreign-Function-Interface_002c-generation"></a>

<p>The <code>sb-grovel</code> module helps in generation of foreign function
interfaces. It aids in extracting constants&rsquo; values from the C
compiler and in generating SB-ALIEN structure and union types,
see <a href="#Defining-Foreign-Types">Defining Foreign Types</a>.
</p>
<p>The ASDF(<a href="http://www.cliki.net/ASDF">http://www.cliki.net/ASDF</a>) 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.
</p>
<p>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.
</p>
<a name="Using-sb_002dgrovel-in-your-own-ASDF-system"></a>
<h4 class="subsection">16.4.1 Using sb-grovel in your own ASDF system</h4>

<ol>
<li> Create a Lisp package for the foreign constants/functions to go into.

</li><li> Make your system depend on the &rsquo;sb-grovel system.

</li><li> Create a grovel-constants data file - for an example, see
example-constants.lisp in the contrib/sb-grovel/ directory in the SBCL
source distribution.

</li><li> Add it as a component in your system. e.g.

<div class="lisp">
<pre class="lisp">(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 &quot;sbcl&quot;
              :components
              ((:file &quot;defpackage&quot;)
               (grovel-constants-file &quot;example-constants&quot;
                                      :package :example-package)))))
</pre></div>

<p>Make sure to specify the package you chose in step 1
</p>
</li><li> Build stuff.

</li></ol>

<a name="Contents-of-a-grovel_002dconstants_002dfile"></a>
<h4 class="subsection">16.4.2 Contents of a grovel-constants-file</h4>

<p>The grovel-constants-file, typically named <code>constants.lisp</code>,
comprises lisp expressions describing the foreign things that you want
to grovel for. A <code>constants.lisp</code> file contains two sections:
</p>
<ul>
<li> a list of headers to include in the C program, for example:
<div class="lisp">
<pre class="lisp">(&quot;sys/types.h&quot; &quot;sys/socket.h&quot; &quot;sys/stat.h&quot; &quot;unistd.h&quot; &quot;sys/un.h&quot;
 &quot;netinet/in.h&quot; &quot;netinet/in_systm.h&quot; &quot;netinet/ip.h&quot; &quot;net/if.h&quot;
 &quot;netdb.h&quot; &quot;errno.h&quot; &quot;netinet/tcp.h&quot; &quot;fcntl.h&quot; &quot;signal.h&quot; )
</pre></div>

</li><li> A list of sb-grovel clauses describing the things you want to grovel
from the C compiler, for example:
<div class="lisp">
<pre class="lisp">((:integer af-local
           #+(or sunos solaris) &quot;AF_UNIX&quot;
           #-(or sunos solaris) &quot;AF_LOCAL&quot;
           &quot;Local to host (pipes and file-domain).&quot;)
 (:structure stat (&quot;struct stat&quot;
                   (integer dev &quot;dev_t&quot; &quot;st_dev&quot;)
                   (integer atime &quot;time_t&quot; &quot;st_atime&quot;)))
 (:function getpid (&quot;getpid&quot; int )))
</pre></div>
</li></ul>

<p>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&rsquo;t use any information from the C program; they
expand directly to <code>sb-alien:define-alien-routine</code>
(see <a href="#The-define_002dalien_002droutine-Macro">The define-alien-routine Macro</a>) forms.
</p>
<p>Here&rsquo;s how to use the grovel clauses:
</p>
<ul>
<li> <code>:integer</code> - constant expressions in C. Used in this form:
<div class="lisp">
<pre class="lisp"> (:integer lisp-variable-name &quot;C expression&quot; &amp;optional doc export)
</pre></div>

<p><code>&quot;C expression&quot;</code> will be typically be the name of a constant. But
other forms are possible.
</p>
</li><li> <code>:enum</code>
<div class="lisp">
<pre class="lisp"> (:enum lisp-type-name ((lisp-enumerated-name c-enumerated-name) ...)))
</pre></div>

<p>An <code>sb-alien:enum</code> type with name <code>lisp-type-name</code> will be defined.
The symbols are the <code>lisp-enumerated-name</code>s, and the values
are grovelled from the <code>c-enumerated-name</code>s.
</p>
</li><li> <code>:structure</code> - alien structure definitions look like this:
<div class="lisp">
<pre class="lisp"> (:structure lisp-struct-name (&quot;struct c_structure&quot;
                               (type-designator lisp-element-name
                                &quot;c_element_type&quot; &quot;c_element_name&quot;
                                :distrust-length nil)
                               ; ...
                               ))
</pre></div>

<p><code>type-designator</code> 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&rsquo;t quite conform to either lisp nor sb-alien&rsquo;s
type specifiers. Here&rsquo;s a list of type designators that sb-grovel
currently accepts:
</p><ul>
<li> <code>integer</code> - 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.

</li><li> <code>(unsigned n)</code> - an unsigned integer variable that is <code>n</code>
bytes long. No size information from the C program will be used.
</li><li> <code>(signed n)</code> - an signed integer variable that is <code>n</code> bytes
long. No size information from the C program will be used.

</li><li> <code>c-string</code> - an array of <code>char</code> in the structure. sb-grovel
will use the array&rsquo;s length from the C program, unless you pass it the
<code>:distrust-length</code> keyword argument with non-<code>nil</code> value
(this might be required for structures such as solaris&rsquo;s <code>struct
dirent</code>).

</li><li> <code>c-string-pointer</code> - a pointer to a C string, corresponding to
the <code>sb-alien:c-string</code> type (see <a href="#Foreign-Type-Specifiers">Foreign Type Specifiers</a>).
</li><li> <code>(array alien-type)</code> - An array of the previously-declared alien
type. The array&rsquo;s size will be determined from the output of the C
program and the alien type&rsquo;s size.
</li><li> <code>(array alien-type n)</code> - An array of the previously-declared alien
type. The array&rsquo;s size will be assumed as being <code>n</code>.
</li></ul>


<p>Note that <code>c-string</code> and <code>c-string-pointer</code> do not have the
same meaning. If you declare that an element is of type
<code>c-string</code>, it will be treated as if the string is a part of the
structure, whereas if you declare that the element is of type
<code>c-string-pointer</code>, a <em>pointer to a string</em> will be the
structure member.
</p>
</li><li> <code>:function</code> - alien function definitions are similar to
<code>define-alien-routine</code> definitions, because they expand to such
forms when the lisp program is loaded. See <a href="#Foreign-Function-Calls">Foreign Function Calls</a>.

<div class="lisp">
<pre class="lisp">(:function lisp-function-name (&quot;alien_function_name&quot; alien-return-type
                                                     (argument alien-type)
                                                     (argument2 alien-type)))
</pre></div>
</li></ul>


<a name="Programming-with-sb_002dgrovel_0027s-structure-types"></a>
<h4 class="subsection">16.4.3 Programming with sb-grovel&rsquo;s structure types</h4>

<p>Let us assume that you have a grovelled structure definition:
</p><div class="lisp">
<pre class="lisp"> (:structure mystruct (&quot;struct my_structure&quot;
                       (integer myint &quot;int&quot; &quot;st_int&quot;)
                       (c-string mystring &quot;char[]&quot; &quot;st_str&quot;)))
</pre></div>

<p>What can you do with it? Here&rsquo;s a short interface document:
</p>
<ul>
<li> Creating and destroying objects:
<ul>
<li> Function <code>(allocate-mystruct)</code> - allocates an object of type <code>mystruct</code>and
returns a system area pointer to it.
</li><li> Function <code>(free-mystruct var)</code> - frees the alien object pointed to by
<var>var</var>.
</li><li> Macro <code>(with-mystruct var ((member init) [...]) &amp;body body)</code> -
allocates an object of type <code>mystruct</code> that is valid in
<var>body</var>. If <var>body</var> terminates or control unwinds out of
<var>body</var>, the object pointed to by <var>var</var> will be deallocated.
</li></ul>

</li><li> Accessing structure members:
<ul>
<li> <code>(mystruct-myint var)</code> and <code>(mystruct-mystring var)</code> return
the value of the respective fields in <code>mystruct</code>.
</li><li> <code>(setf (mystruct-myint var) new-val)</code> and
<code>(setf (mystruct-mystring var) new-val)</code> sets the value of the respective
structure member to the value of <var>new-val</var>. Notice that in
<code>(setf (mystruct-mystring var) new-val)</code>&rsquo;s case, new-val is a lisp
string.
</li></ul>
</li></ul>

<a name="Traps-and-Pitfalls"></a>
<h4 class="subsubsection">16.4.3.1 Traps and Pitfalls</h4>
<p>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&rsquo;t
use alien types):
</p>
<ul>
<li> 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.

</li><li> If you use the <code>with-mystruct</code> macro, be sure that no references
to the variable thus allocated leaks out. It will be deallocated when
the block exits.
</li></ul>

<hr>
<a name="sb_002dmd5"></a>
<div class="header">
<p>
Next: <a href="#sb_002dposix" accesskey="n" rel="next">sb-posix</a>, Previous: <a href="#sb_002dgrovel" accesskey="p" rel="prev">sb-grovel</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dmd5-1"></a>
<h3 class="section">16.5 sb-md5</h3>
<a name="index-Hashing_002c-cryptographic"></a>

<p>The <code>sb-md5</code> module implements the RFC1321 MD5 Message Digest
Algorithm. [FIXME cite]
</p>
<a name="Function-sb_002dmd5_003amd5sum_002dfile"></a><dl>
<dt><a name="index-md5sum_002dfile"></a>Function: <strong>md5sum-file</strong> <em>[sb-md5] pathname</em></dt>
<dd><p>Calculate the MD5 message-digest of the file designated by
pathname.
</p></dd></dl>

<a name="Function-sb_002dmd5_003amd5sum_002dsequence"></a><dl>
<dt><a name="index-md5sum_002dsequence"></a>Function: <strong>md5sum-sequence</strong> <em>[sb-md5] sequence &amp;key start end</em></dt>
<dd><p>Calculate the MD5 message-digest of data bounded by <code>start</code> and <code>end</code>
in <code>sequence</code> , which must be a vector with element-type (UNSIGNED-BYTE
8).
</p></dd></dl>

<a name="Function-sb_002dmd5_003amd5sum_002dstream"></a><dl>
<dt><a name="index-md5sum_002dstream"></a>Function: <strong>md5sum-stream</strong> <em>[sb-md5] stream</em></dt>
<dd><p>Calculate an MD5 message-digest of the contents of <code>stream</code>, whose
element-type has to be <code>(unsigned-byte 8)</code>.
</p></dd></dl>

<a name="Function-sb_002dmd5_003amd5sum_002dstring"></a><dl>
<dt><a name="index-md5sum_002dstring"></a>Function: <strong>md5sum-string</strong> <em>[sb-md5] string &amp;key external-format start end</em></dt>
<dd><p>Calculate the MD5 message-digest of the binary representation
of <code>string</code> (as octets) in <code>external-format</code>. The boundaries <code>start</code>
and <code>end</code> refer to character positions in the string, not to octets
in the resulting binary representation.
</p></dd></dl>

<a name="Credits-2"></a>
<h4 class="subsection">16.5.1 Credits</h4>

<p>The implementation for CMUCL was largely done by Pierre Mai, with help
from members of the <code>cmucl-help</code> 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&rsquo;s compiler was extended to implement efficient
compilation of modular arithmetic (see <a href="#Modular-arithmetic">Modular arithmetic</a>), which
enabled the implementation to be expressed in portable arithmetical
terms, apart from the use of <code>rotate-byte</code> for bitwise rotation.
<a name="index-rotate_002dbyte-_005bsb_002drotate_002dbyte_005d"></a>
</p>

<hr>
<a name="sb_002dposix"></a>
<div class="header">
<p>
Next: <a href="#sb_002dqueue" accesskey="n" rel="next">sb-queue</a>, Previous: <a href="#sb_002dmd5" accesskey="p" rel="prev">sb-md5</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dposix-1"></a>
<h3 class="section">16.6 sb-posix</h3>
<a name="index-Operating-System-Interface"></a>
<a name="index-System-Calls"></a>
<a name="index-Posix"></a>

<p>Sb-posix is the supported interface for calling out to the operating
system.<a name="DOCF10" href="#FOOT10"><sup>10</sup></a>
</p>
<p>The scope of this interface is &ldquo;operating system calls on a typical
Unixlike platform&rdquo;.  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
<code>opendir()</code> and <code>readdir()</code>, but not for <code>printf()</code>.
That said, if your favourite system call is not included yet, you are
encouraged to submit a patch to the SBCL mailing list.
</p>
<p>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.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Lisp-names-for-C-names" accesskey="1">Lisp names for C names</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Types" accesskey="2">Types</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Function-Parameters" accesskey="3">Function Parameters</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Function-Return-Values" accesskey="4">Function Return Values</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Lisp-objects-and-C-structures" accesskey="5">Lisp objects and C structures</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Functions-with-idiosyncratic-bindings" accesskey="6">Functions with idiosyncratic bindings</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>


<hr>
<a name="Lisp-names-for-C-names"></a>
<div class="header">
<p>
Next: <a href="#Types" accesskey="n" rel="next">Types</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Lisp-names-for-C-names-1"></a>
<h4 class="subsection">16.6.1 Lisp names for C names</h4>

<p>All symbols are in the <code>SB-POSIX</code> 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&rsquo;s name, by (a) uppercasing, then (b) removing leading
underscores (<code>#\_</code>) then replacing remaining underscore characters
with the hyphen (<code>#\-</code>). The requirement to uppercase is so that in
a standard upcasing reader the user may write <code>sb-posix:creat</code>
instead of <code>sb-posix:|creat|</code> as would otherise be required.
</p>
<p>No other changes to &ldquo;Lispify&rdquo; symbol names are made, so <code>creat()</code>
becomes <code>CREAT</code>, not <code>CREATE</code>.
</p>
<p>The user is encouraged not to <code>(USE-PACKAGE :SB-POSIX)</code> but instead
to use the <code>SB-POSIX:</code> prefix on all references, as some of the
symbols symbols contained in the SB-POSIX package have the same name as
CL symbols (<code>OPEN</code>, <code>CLOSE</code>, <code>SIGNAL</code> etc).
</p>
<hr>
<a name="Types"></a>
<div class="header">
<p>
Next: <a href="#Function-Parameters" accesskey="n" rel="next">Function Parameters</a>, Previous: <a href="#Lisp-names-for-C-names" accesskey="p" rel="prev">Lisp names for C names</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Types-1"></a>
<h4 class="subsection">16.6.2 Types</h4>

<p>Generally, marshalling between Lisp and C data types is done using
SBCL&rsquo;s FFI. See <a href="#Foreign-Function-Interface">Foreign Function Interface</a>.
</p>
<p>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&rsquo;s convenience we
introduce designators such that CL pathnames or open streams can be
passed to these functions.  For example, <code>rename</code> accepts both
pathnames and strings as its arguments.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#File_002ddescriptors" accesskey="1">File-descriptors</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Filenames" accesskey="2">Filenames</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="File_002ddescriptors"></a>
<div class="header">
<p>
Next: <a href="#Filenames" accesskey="n" rel="next">Filenames</a>, Up: <a href="#Types" accesskey="u" rel="up">Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="File_002ddescriptors-1"></a>
<h4 class="subsubsection">16.6.2.1 File-descriptors</h4>

<a name="Type-sb_002dposix_003afile_002ddescriptor"></a><dl>
<dt><a name="index-file_002ddescriptor-1"></a>Type: <strong>file-descriptor</strong> <em>[sb-posix]</em></dt>
<dd><p>A <code>fixnum</code> designating a native file descriptor.
</p>
<p><code>sb-sys:make-fd-stream</code> can be used to construct a <code>file-stream</code> associated with a
native file descriptor.
</p>
<p>Note that mixing I/O operations on a <code>file-stream</code> with operations directly on its
descriptor may produce unexpected results if the stream is buffered.
</p></dd></dl>
<a name="Type-sb_002dposix_003afile_002ddescriptor_002ddesignator"></a><dl>
<dt><a name="index-file_002ddescriptor_002ddesignator"></a>Type: <strong>file-descriptor-designator</strong> <em>[sb-posix]</em></dt>
<dd><p>Designator for a <code>file-descriptor:</code> either a fixnum designating itself, or
a <code>file-stream</code> designating the underlying file-descriptor.
</p></dd></dl>
<a name="Function-sb_002dposix_003afile_002ddescriptor"></a><dl>
<dt><a name="index-file_002ddescriptor"></a>Function: <strong>file-descriptor</strong> <em>[sb-posix] file-descriptor</em></dt>
<dd><p>Converts <code>file-descriptor-designator</code> into a <code>file-descriptor</code>.
</p></dd></dl>

<hr>
<a name="Filenames"></a>
<div class="header">
<p>
Previous: <a href="#File_002ddescriptors" accesskey="p" rel="prev">File-descriptors</a>, Up: <a href="#Types" accesskey="u" rel="up">Types</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Filenames-1"></a>
<h4 class="subsubsection">16.6.2.2 Filenames</h4>

<a name="Type-sb_002dposix_003afilename"></a><dl>
<dt><a name="index-filename-1"></a>Type: <strong>filename</strong> <em>[sb-posix]</em></dt>
<dd><p>A <code>string</code> designating a filename in native namestring syntax.
</p>
<p>Note that native namestring syntax is distinct from Lisp namestring syntax:
</p>
<div class="lisp">
<pre class="lisp">  (pathname &quot;/foo*/bar&quot;)
</pre></div>

<p>is a wild pathname with a pattern-matching directory component.
<code>sb-ext:parse-native-namestring</code> may be used to construct Lisp pathnames that
denote <code>posix</code> filenames as understood by system calls, and
<code>sb-ext:native-namestring</code> can be used to coerce them into strings in the native
namestring syntax.
</p>
<p>Note also that <code>posix</code> filename syntax does not distinguish the names of files
from the names of directories: in order to parse the name of a directory in
<code>posix</code> filename syntax into a pathname <code>my-defaults</code> for which
</p>
<div class="lisp">
<pre class="lisp">  (merge-pathnames (make-pathname :name &quot;FOO&quot; :case :common)
                    my-defaults)
</pre></div>

<p>returns a pathname that denotes a file in the directory, supply a true
<code>:as-directory</code> argument to <code>sb-ext:parse-native-namestring</code>. Likewise, to supply
the name of a directory to a <code>posix</code> function in non-directory syntax, supply a
true <code>:as-file</code> argument to <code>sb-ext:native-namestring</code>.
</p></dd></dl>
<a name="Type-sb_002dposix_003afilename_002ddesignator"></a><dl>
<dt><a name="index-filename_002ddesignator"></a>Type: <strong>filename-designator</strong> <em>[sb-posix]</em></dt>
<dd><p>Designator for a <code>filename:</code> a <code>string</code> designating itself, or a
designator for a <code>pathname</code> designating the corresponding native namestring.
</p></dd></dl>
<a name="Function-sb_002dposix_003afilename"></a><dl>
<dt><a name="index-filename"></a>Function: <strong>filename</strong> <em>[sb-posix] filename</em></dt>
<dd><p>Converts <code>filename-designator</code> into a <code>filename</code>.
</p></dd></dl>

<hr>
<a name="Function-Parameters"></a>
<div class="header">
<p>
Next: <a href="#Function-Return-Values" accesskey="n" rel="next">Function Return Values</a>, Previous: <a href="#Types" accesskey="p" rel="prev">Types</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Function-Parameters-1"></a>
<h4 class="subsection">16.6.3 Function Parameters</h4>

<p>The calling convention is modelled after that of CMUCL&rsquo;s <code>UNIX</code>
package: in particular, it&rsquo;s like the C interface except that:
</p>
<ol>
<li> Length arguments are omitted or optional where the sensible value
is obvious.  For example, <code>read</code> would be defined this way:

<div class="lisp">
<pre class="lisp">(read fd buffer &amp;optional (length (length buffer))) =&gt; bytes-read
</pre></div>

</li><li> Where C simulates &ldquo;out&rdquo; parameters using pointers (for instance, in
<code>pipe()</code> or <code>socketpair()</code>) 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).

</li><li> 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 &rsquo;Types&rsquo;
section above.

</li><li> A few functions have been included in sb-posix that do not correspond
exactly with their C counterparts.  These are described in
See <a href="#Functions-with-idiosyncratic-bindings">Functions with idiosyncratic bindings</a>.

</li></ol>

<hr>
<a name="Function-Return-Values"></a>
<div class="header">
<p>
Next: <a href="#Lisp-objects-and-C-structures" accesskey="n" rel="next">Lisp objects and C structures</a>, Previous: <a href="#Function-Parameters" accesskey="p" rel="prev">Function Parameters</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Function-Return-Values-1"></a>
<h4 class="subsection">16.6.4 Function Return Values</h4>

<p>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 <code>errno</code> on error, we instead signal an error of
type <code>SYSCALL-ERROR</code>.  The actual error value (<code>errno</code>) is
stored in this condition and can be accessed with <code>SYSCALL-ERRNO</code>.
</p>
<p>We do not automatically translate the returned value into &ldquo;Lispy&rdquo;
objects &ndash; for example, <code>SB-POSIX:OPEN</code> 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.
</p>
<hr>
<a name="Lisp-objects-and-C-structures"></a>
<div class="header">
<p>
Next: <a href="#Functions-with-idiosyncratic-bindings" accesskey="n" rel="next">Functions with idiosyncratic bindings</a>, Previous: <a href="#Function-Return-Values" accesskey="p" rel="prev">Function Return Values</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Lisp-objects-and-C-structures-1"></a>
<h4 class="subsection">16.6.5 Lisp objects and C structures</h4>

<p>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.
</p>
<p>The names of the Lisp types are chosen according to the general rules
described above.  For example Lisp objects of type <code>STAT</code> stand
in for C structures of type <code>struct stat</code>.
</p>
<p>Accessors are provided for each standard field in the structure. These
are named <code><var>structure-name</var>-<var>field-name</var></code> 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,
<code>stat.st_dev</code> in C becomes <code>STAT-DEV</code> in Lisp.
</p>


<p>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.
</p>
<ul>
<li> flock
<a name="Class-sb_002dposix_003aflock"></a><dl>
<dt><a name="index-flock"></a>Class: <strong>flock</strong> <em>[sb-posix]</em></dt>
<dd><p>Class precedence list: <code>flock, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>type</code> &mdash; initarg: <code>:type<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:flock-type</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:flock-type)</span><!-- /@w --></code>

<p>Type of lock; F_RDLCK, F_WRLCK, F_UNLCK.
</p></li><li> <code>whence</code> &mdash; initarg: <code>:whence<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:flock-whence</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:flock-whence)</span><!-- /@w --></code>

<p>Flag for starting offset.
</p></li><li> <code>start</code> &mdash; initarg: <code>:start<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:flock-start</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:flock-start)</span><!-- /@w --></code>

<p>Relative offset in bytes.
</p></li><li> <code>len</code> &mdash; initarg: <code>:len<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:flock-len</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:flock-len)</span><!-- /@w --></code>

<p>Size; if 0 then until <code>eof</code>.
</p></li><li> <code>pid</code> &mdash; reader: <code><span class="nolinebreak">sb-posix:flock-pid</span><!-- /@w --></code>

<p>Process <code>id</code> of the process holding the lock; returned with F_GETLK.
</p></li></ul>

<p>Class representing locks used in fcntl(2).
</p></dd></dl>

</li><li> passwd
<a name="Class-sb_002dposix_003apasswd"></a><dl>
<dt><a name="index-passwd"></a>Class: <strong>passwd</strong> <em>[sb-posix]</em></dt>
<dd><p>Class precedence list: <code>passwd, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>name</code> &mdash; initarg: <code>:name<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-name</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-name)</span><!-- /@w --></code>

<p>User&rsquo;s login name.
</p></li><li> <code>passwd</code> &mdash; initarg: <code>:passwd<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-passwd</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-passwd)</span><!-- /@w --></code>

<p>The account&rsquo;s encrypted password.
</p></li><li> <code>uid</code> &mdash; initarg: <code>:uid<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-uid</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-uid)</span><!-- /@w --></code>

<p>Numerical user <code>id</code>.
</p></li><li> <code>gid</code> &mdash; initarg: <code>:gid<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-gid</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-gid)</span><!-- /@w --></code>

<p>Numerical group <code>id</code>.
</p></li><li> <code>gecos</code> &mdash; initarg: <code>:gecos<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-gecos</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-gecos)</span><!-- /@w --></code>

<p>User&rsquo;s name or comment field.
</p></li><li> <code>dir</code> &mdash; initarg: <code>:dir<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-dir</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-dir)</span><!-- /@w --></code>

<p>Initial working directory.
</p></li><li> <code>shell</code> &mdash; initarg: <code>:shell<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:passwd-shell</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:passwd-shell)</span><!-- /@w --></code>

<p>Program to use as shell.
</p></li></ul>

<p>Instances of this class represent entries in the system&rsquo;s user database.
</p></dd></dl>

</li><li> stat
<a name="Class-sb_002dposix_003astat"></a><dl>
<dt><a name="index-stat"></a>Class: <strong>stat</strong> <em>[sb-posix]</em></dt>
<dd><p>Class precedence list: <code>stat, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>mode</code> &mdash; initarg: <code>:mode<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-mode</span><!-- /@w --></code>

<p>Mode of file.
</p></li><li> <code>ino</code> &mdash; initarg: <code>:ino<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-ino</span><!-- /@w --></code>

<p>File serial number.
</p></li><li> <code>dev</code> &mdash; initarg: <code>:dev<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-dev</span><!-- /@w --></code>

<p>Device <code>id</code> of device containing file.
</p></li><li> <code>nlink</code> &mdash; initarg: <code>:nlink<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-nlink</span><!-- /@w --></code>

<p>Number of hard links to the file.
</p></li><li> <code>uid</code> &mdash; initarg: <code>:uid<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-uid</span><!-- /@w --></code>

<p>User <code>id</code> of file.
</p></li><li> <code>gid</code> &mdash; initarg: <code>:gid<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-gid</span><!-- /@w --></code>

<p>Group <code>id</code> of file.
</p></li><li> <code>size</code> &mdash; initarg: <code>:size<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-size</span><!-- /@w --></code>

<p>For regular files, the file size in
                         bytes.  For symbolic links, the length
                         in bytes of the filename contained in
                         the symbolic link.
</p></li><li> <code>rdev</code> &mdash; initarg: <code>:rdev<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-rdev</span><!-- /@w --></code>

<p>For devices the device number.
</p></li><li> <code>atime</code> &mdash; initarg: <code>:atime<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-atime</span><!-- /@w --></code>

<p>Time of last access.
</p></li><li> <code>mtime</code> &mdash; initarg: <code>:mtime<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-mtime</span><!-- /@w --></code>

<p>Time of last data modification.
</p></li><li> <code>ctime</code> &mdash; initarg: <code>:ctime<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:stat-ctime</span><!-- /@w --></code>

<p>Time of last status change.
</p></li></ul>

<p>Instances of this class represent <code>posix</code> file metadata.
</p></dd></dl>

</li><li> termios
<a name="Class-sb_002dposix_003atermios"></a><dl>
<dt><a name="index-termios"></a>Class: <strong>termios</strong> <em>[sb-posix]</em></dt>
<dd><p>Class precedence list: <code>termios, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>iflag</code> &mdash; initarg: <code>:iflag<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:termios-iflag</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:termios-iflag)</span><!-- /@w --></code>

<p>Input modes.
</p></li><li> <code>oflag</code> &mdash; initarg: <code>:oflag<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:termios-oflag</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:termios-oflag)</span><!-- /@w --></code>

<p>Output modes.
</p></li><li> <code>cflag</code> &mdash; initarg: <code>:cflag<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:termios-cflag</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:termios-cflag)</span><!-- /@w --></code>

<p>Control modes.
</p></li><li> <code>lflag</code> &mdash; initarg: <code>:lflag<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:termios-lflag</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:termios-lflag)</span><!-- /@w --></code>

<p>Local modes.
</p></li><li> <code>cc</code> &mdash; initarg: <code>:cc<!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:termios-cc</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:termios-cc)</span><!-- /@w --></code>

<p>Control characters.
</p></li></ul>

<p>Instances of this class represent I/O characteristics of the terminal.
</p></dd></dl>

</li><li> timeval
<a name="Class-sb_002dposix_003atimeval"></a><dl>
<dt><a name="index-timeval"></a>Class: <strong>timeval</strong> <em>[sb-posix]</em></dt>
<dd><p>Class precedence list: <code>timeval, standard-object, t</code>
</p>
<p>Slots:
</p><ul>
<li> <code>sec</code> &mdash; initarg: <code><span class="nolinebreak">:tv-sec</span><!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:timeval-sec</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:timeval-sec)</span><!-- /@w --></code>

<p>Seconds.
</p></li><li> <code>usec</code> &mdash; initarg: <code><span class="nolinebreak">:tv-usec</span><!-- /@w --></code>; reader: <code><span class="nolinebreak">sb-posix:timeval-usec</span><!-- /@w --></code>; writer: <code>(setf&nbsp;<span class="nolinebreak">sb-posix:timeval-usec)</span><!-- /@w --></code>

<p>Microseconds.
</p></li></ul>

<p>Instances of this class represent time values.
</p></dd></dl>
</li></ul>

<hr>
<a name="Functions-with-idiosyncratic-bindings"></a>
<div class="header">
<p>
Previous: <a href="#Lisp-objects-and-C-structures" accesskey="p" rel="prev">Lisp objects and C structures</a>, Up: <a href="#sb_002dposix" accesskey="u" rel="up">sb-posix</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Functions-with-idiosyncratic-bindings-1"></a>
<h4 class="subsection">16.6.6 Functions with idiosyncratic bindings</h4>

<p>A few functions in sb-posix don&rsquo;t correspond directly to their C
counterparts.
</p>
<ul>
<li> getcwd
<a name="Function-sb_002dposix_003agetcwd"></a><dl>
<dt><a name="index-getcwd"></a>Function: <strong>getcwd</strong> <em>[sb-posix]</em></dt>
<dd><p>Returns the process&rsquo;s current working directory as a string.
</p></dd></dl>
</li><li> readlink
<a name="Function-sb_002dposix_003areadlink"></a><dl>
<dt><a name="index-readlink"></a>Function: <strong>readlink</strong> <em>[sb-posix] pathspec</em></dt>
<dd><p>Returns the resolved target of a symbolic link as a string.
</p></dd></dl>
</li><li> syslog
<a name="Function-sb_002dposix_003asyslog"></a><dl>
<dt><a name="index-syslog"></a>Function: <strong>syslog</strong> <em>[sb-posix] priority format &amp;rest args</em></dt>
<dd><p>Send a message to the syslog facility, with severity level
<code>priority</code>.  The message will be formatted as by <code>cl:format</code> (rather
than C&rsquo;s printf) with format string <code>format</code> and arguments <code>args</code>.
</p></dd></dl>
</li></ul>

<hr>
<a name="sb_002dqueue"></a>
<div class="header">
<p>
Next: <a href="#sb_002drotate_002dbyte" accesskey="n" rel="next">sb-rotate-byte</a>, Previous: <a href="#sb_002dposix" accesskey="p" rel="prev">sb-posix</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002dqueue-1"></a>
<h3 class="section">16.7 sb-queue</h3>
<a name="index-Queue_002c-FIFO"></a>

<p>Since SBCL 1.0.38, the <code>sb-queue</code> module has been merged into the
<code>sb-concurrency</code> module (see <a href="#sb_002dconcurrency">sb-concurrency</a>.)
</p>
<hr>
<a name="sb_002drotate_002dbyte"></a>
<div class="header">
<p>
Previous: <a href="#sb_002dqueue" accesskey="p" rel="prev">sb-queue</a>, Up: <a href="#Contributed-Modules" accesskey="u" rel="up">Contributed Modules</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="sb_002drotate_002dbyte-1"></a>
<h3 class="section">16.8 sb-rotate-byte</h3>
<a name="index-Modular-arithmetic-1"></a>
<a name="index-Arithmetic_002c-modular-1"></a>
<a name="index-Arithmetic_002c-hardware-1"></a>

<p>The <code>sb-rotate-byte</code> module offers an interface to bitwise
rotation, with an efficient implementation for operations which can be
performed directly using the platform&rsquo;s arithmetic routines.  It
implements the specification at
<a href="http://www.cliki.net/ROTATE-BYTE">http://www.cliki.net/ROTATE-BYTE</a>.
</p>
<p>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].
</p>
<a name="Function-sb_002drotate_002dbyte_003arotate_002dbyte"></a><dl>
<dt><a name="index-rotate_002dbyte"></a>Function: <strong>rotate-byte</strong> <em>[sb-rotate-byte] count bytespec integer</em></dt>
<dd><p>Rotates a field of bits within <code>integer</code>; specifically, returns an
integer that contains the bits of <code>integer</code> rotated <code>count</code> times
leftwards within the byte specified by <code>bytespec</code>, and elsewhere
contains the bits of <code>integer</code>.
</p></dd></dl>


<hr>
<a name="Deprecation"></a>
<div class="header">
<p>
Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Contributed-Modules" accesskey="p" rel="prev">Contributed Modules</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecation-1"></a>
<h2 class="chapter">17 Deprecation</h2>

<p>In order to support evolution of interfaces in SBCL as well as in user
code, SBCL allows declaring functions, variables and types as
deprecated. Users of deprecated things are notified by means of warnings
while the deprecated thing in question is still available.
</p>
<p>This chapter documents the interfaces for being notified when using
deprecated thing and declaring things as deprecated, the deprecation
process used for SBCL interfaces, and lists legacy interfaces in various
stages of deprecation.
</p>
<p><em>Deprecation</em> in this context should not be confused with those
things the ANSI Common Lisp standard calls <em>deprecated</em>: the
entirety of ANSI CL is supported by SBCL, and none of those interfaces
are subject to censure.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="#Why-Deprecate_003f" accesskey="1">Why Deprecate?</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#The-Deprecation-Pipeline" accesskey="2">The Deprecation Pipeline</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Deprecation-Conditions" accesskey="3">Deprecation Conditions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Introspecting-Deprecation-Information" accesskey="4">Introspecting Deprecation Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Deprecation-Declaration" accesskey="5">Deprecation Declaration</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Deprecation-Examples" accesskey="6">Deprecation Examples</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="#Deprecated-Interfaces-in-SBCL" accesskey="7">Deprecated Interfaces in SBCL</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
</table>

<hr>
<a name="Why-Deprecate_003f"></a>
<div class="header">
<p>
Next: <a href="#The-Deprecation-Pipeline" accesskey="n" rel="next">The Deprecation Pipeline</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Why-Deprecate_003f-1"></a>
<h3 class="section">17.1 Why Deprecate?</h3>
<a name="index-Why-Deprecate_003f"></a>

<p>While generally speaking we try to keep SBCL changes as backwards
compatible as feasible, there are situations when existing interfaces
are deprecated:
</p>
<ul>
<li> <strong>Broken Interfaces</strong>

<p>Sometimes it turns out that an interface is sufficiently misdesigned
that fixing it would be worse than deprecating it and replacing it
with another.
</p>
<p>This is typically the case when fixing the interface would change its
semantics in ways that could break user code subtly: in such cases we
may end up considering the obvious breakage caused by deprecation to
be preferable.
</p>
<p>Another example are functions or macros whose current signature makes
them hard or impossible to extend in the future: backwards compatible
extensions would either make the interface intolerably hairy, or are
sometimes outright impossible.
</p>
</li><li> <strong>Internal Interfaces</strong>

<p>SBCL has several internal interfaces that were never meant to be used
in user code &ndash; or at least never meant to be used in user code
unwilling to track changes to SBCL internals.
</p>
<p>Ideally we&rsquo;d like to be free to refactor our own internals as we
please, without even going through the hassle of deprecating things.
Sometimes, however, it turns out that our internal interfaces have
several external users who aren&rsquo;t using them advisedly, but due to
misunderstandings regarding their status or stability.
</p>
<p>Consider a deprecated internal interface a reminder for SBCL
maintainers not to delete the thing just yet, even though it is seems
unused &ndash; because it has external users.
</p>
<p>When internal interfaces are deprecated we try our best to provide
supported alternatives.
</p>
</li><li> <strong>Aesthetics &amp; Ease of Maintenance</strong>

<p>Sometimes an interface isn&rsquo;t broken or internal, but just inconsistent
somehow.
</p>
<p>This mostly happens only with historical interfaces inherited from
CMUCL which often haven&rsquo;t been officially supported in SBCL before, or
with new extensions to SBCL that haven&rsquo;t been around for very long in
the first place.
</p>
<p>The alternative would be to keep the suboptimal version around
forever, possibly alongside an improved version. Sometimes we may do
just that, but because every line of code comes with a maintenance
cost, sometimes we opt to deprecate the suboptimal version instead:
SBCL doesn&rsquo;t have infinite developer resources.
</p>
<p>We also believe that sometimes cleaning out legacy interfaces helps
keep the whole system more comprehensible to users, and makes
introspective tools such as <code>apropos</code> more useful.
</p>
</li></ul>

<hr>
<a name="The-Deprecation-Pipeline"></a>
<div class="header">
<p>
Next: <a href="#Deprecation-Conditions" accesskey="n" rel="next">Deprecation Conditions</a>, Previous: <a href="#Why-Deprecate_003f" accesskey="p" rel="prev">Why Deprecate?</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="The-Deprecation-Pipeline-1"></a>
<h3 class="section">17.2 The Deprecation Pipeline</h3>
<a name="index-The-Deprecation-Pipeline"></a>

<p>SBCL uses a <em>deprecation pipeline</em> with multiple stages: as time
goes by, deprecated things move from earlier stages of deprecation to
later stages before finally being removed. The intention is making users
aware of necessary changes early but allowing a migration to new
interfaces at a reasonable pace.
</p>
<p>Deprecation proceeds in three stages, each lasting approximately a
year. In some cases it might move slower or faster, but one year per
stage is what we aim at in general. During each stage warnings (and
errors) of increasing severity are signaled, which note that the
interface is deprecated, and point users towards any replacements when
applicable.
</p>
<ol>
<li> <strong>Early Deprecation</strong>

<p>During early deprecation the interface is kept in working
condition. However, when a thing in this deprecation stage is used, an
early-deprecation-warning [sb-ext], which is a style-warning [cl], is
signaled at compile-time.
</p>
<p>The internals may change at this stage: typically because the interface
is re-implemented on top of its successor. While we try to keep things
as backwards-compatible as feasible (taking maintenance costs into account),
sometimes semantics change slightly.
</p>
<p>For example, when the spinlock API was deprecated, spinlock objects ceased
to exist, and the whole spinlock API became a synonym for the mutex
API &ndash; so code using the spinlock API continued working, but silently
switched to mutexes instead. However, if someone relied on
</p>
<p><code>(typep lock 'spinlock)</code>
</p>
<p>returning <code>NIL</code> for a mutexes, trouble could ensue.
</p>
</li><li> <strong>Late Deprecation</strong>

<p>During late deprecation the interface remains as it was during early
deprecation, but the compile-time warning is upgraded: when a thing in
this deprecation stage is used, a late-deprecation-warning [sb-ext],
which is a full warning [cl], is signaled at compile-time.
</p>
</li><li> <strong>Final Deprecation</strong>

<p>During final deprecation the symbols still exist. However, when a thing
in this deprecation stage is used, a final-deprecation-warning [sb-ext],
which is a full warning [cl], is signaled at compile-time and an
error [cl] is signaled at run-time.
</p>
</li><li> <strong>After Final Deprecation</strong>

<p>The interface is deleted entirely.
</p>
</li></ol>

<hr>
<a name="Deprecation-Conditions"></a>
<div class="header">
<p>
Next: <a href="#Introspecting-Deprecation-Information" accesskey="n" rel="next">Introspecting Deprecation Information</a>, Previous: <a href="#The-Deprecation-Pipeline" accesskey="p" rel="prev">The Deprecation Pipeline</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecation-Conditions-1"></a>
<h3 class="section">17.3 Deprecation Conditions</h3>
<a name="index-Deprecation-Conditions"></a>

<p>deprecation-condition [sb-ext] is the superclass of all
deprecation-related warning and error conditions. All common slots and
readers are defined in this condition class.
</p>
<a name="Condition-sb_002dext_003adeprecation_002dcondition"></a><dl>
<dt><a name="index-deprecation_002dcondition"></a>Condition: <strong>deprecation-condition</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>deprecation-condition, condition, t</code>
</p>
<p>Superclass for deprecation-related error and warning
conditions.
</p></dd></dl>

<a name="Condition-sb_002dext_003aearly_002ddeprecation_002dwarning"></a><dl>
<dt><a name="index-early_002ddeprecation_002dwarning"></a>Condition: <strong>early-deprecation-warning</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>early-deprecation-warning, style-warning, warning, deprecation-condition, condition, t</code>
</p>
<p>This warning is signaled when the use of a variable,
function, type, etc. in <code>:early</code> deprecation is detected at
compile-time. The use will work at run-time with no warning or
error.
</p></dd></dl>

<a name="Condition-sb_002dext_003alate_002ddeprecation_002dwarning"></a><dl>
<dt><a name="index-late_002ddeprecation_002dwarning"></a>Condition: <strong>late-deprecation-warning</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>late-deprecation-warning, warning, deprecation-condition, condition, t</code>
</p>
<p>This warning is signaled when the use of a variable,
function, type, etc. in <code>:late</code> deprecation is detected at
compile-time. The use will work at run-time with no warning or
error.
</p></dd></dl>

<a name="Condition-sb_002dext_003afinal_002ddeprecation_002dwarning"></a><dl>
<dt><a name="index-final_002ddeprecation_002dwarning"></a>Condition: <strong>final-deprecation-warning</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>final-deprecation-warning, warning, deprecation-condition, condition, t</code>
</p>
<p>This warning is signaled when the use of a variable,
function, type, etc. in <code>:final</code> deprecation is detected at
compile-time. An error will be signaled at run-time.
</p></dd></dl>

<a name="Condition-sb_002dext_003adeprecation_002derror"></a><dl>
<dt><a name="index-deprecation_002derror"></a>Condition: <strong>deprecation-error</strong> <em>[sb-ext]</em></dt>
<dd><p>Class precedence list: <code>deprecation-error, error, serious-condition, deprecation-condition, condition, t</code>
</p>
<p>This error is signaled at run-time when an attempt is made to use
a thing that is in <code>:final</code> deprecation, i.e. call a function or access
a variable.
</p></dd></dl>

<hr>
<a name="Introspecting-Deprecation-Information"></a>
<div class="header">
<p>
Next: <a href="#Deprecation-Declaration" accesskey="n" rel="next">Deprecation Declaration</a>, Previous: <a href="#Deprecation-Conditions" accesskey="p" rel="prev">Deprecation Conditions</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Introspecting-Deprecation-Information-1"></a>
<h3 class="section">17.4 Introspecting Deprecation Information</h3>
<a name="index-Introspecting-Deprecation-Information"></a>

<p>The deprecation status of functions and variables can be inspected using
the <code>sb-cltl2:function-information</code> and
<code>sb-cltl2:variable-information</code> functions provided by the
<code>sb-cltl2</code> contributed module.
</p>
<hr>
<a name="Deprecation-Declaration"></a>
<div class="header">
<p>
Next: <a href="#Deprecation-Examples" accesskey="n" rel="next">Deprecation Examples</a>, Previous: <a href="#Introspecting-Deprecation-Information" accesskey="p" rel="prev">Introspecting Deprecation Information</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecation-Declaration-1"></a>
<h3 class="section">17.5 Deprecation Declaration</h3>
<a name="index-Deprecation-Declaration"></a>
<a name="index-deprecated-_005bsb_002dext_005d"></a>

<p>The <code>sb-ext:deprecated</code> declaration can be used to declare objects
in various namespaces<a name="DOCF11" href="#FOOT11"><sup>11</sup></a> as deprecated.
</p>
<dl>
<dt><a name="index-deprecated"></a>Declaration: <strong>deprecated</strong> <em>[sb-ext]</em></dt>
<dd>
<p>Syntax:
</p><div class="example">
<pre class="example"><code>sb-ext:deprecated</code> stage since {object-clause}*

stage ::= {:early | :late | :final}

since ::= {<var>version</var> | (<var>software</var> <var>version</var>)}

object-clause ::= (namespace <var>name</var> [:replacement <var>replacement</var>])

namespace ::= {cl:variable | cl:function | cl:type}
</pre></div>

<p>were <var>name</var> is the name of the deprecated thing,
<var>version</var> and <var>software</var> are strings describing the version in
which the thing has been deprecated and <var>replacement</var> is a name or a
list of names designating things that should be used instead of the
deprecated thing.
</p>
<p>Currently the following namespaces are supported:
</p>
<dl compact="compact">
<dt><code>cl:function</code></dt>
<dd><p>Declare functions, compiler-macros or macros as deprecated.
</p>
<blockquote>
<p><b>note:</b> When declaring a function to be in <code>:final</code> deprecation, there
should be no actual definition of the function as the declaration emits
a stub function that signals a deprecation-error [sb-ext] at run-time
when called.
</p></blockquote>

</dd>
<dt><code>cl:variable</code></dt>
<dd><p>Declare special and global variables, constants and symbol-macros as
deprecated.
</p>
<blockquote>
<p><b>note:</b> When declaring a variable to be in <code>:final</code> deprecation, there
should be no actual definition of the variable as the declaration emits
a symbol-macro that signals a <code>sb-ext:deprecation-error</code> at
run-time when accessed.
</p></blockquote>

</dd>
<dt><code>cl:type</code></dt>
<dd><p>Declare named types (i.e. defined via <code>deftype</code>), standard classes,
structure classes and condition classes as deprecated.
</p>
</dd>
</dl>
</dd></dl>

<hr>
<a name="Deprecation-Examples"></a>
<div class="header">
<p>
Next: <a href="#Deprecated-Interfaces-in-SBCL" accesskey="n" rel="next">Deprecated Interfaces in SBCL</a>, Previous: <a href="#Deprecation-Declaration" accesskey="p" rel="prev">Deprecation Declaration</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecation-Examples-1"></a>
<h3 class="section">17.6 Deprecation Examples</h3>
<a name="index-Deprecation-Examples"></a>

<p>Marking functions as deprecated:
</p><div class="lisp">
<pre class="lisp">(defun foo ())
(defun bar ())
(declaim (deprecated :early (&quot;my-system&quot; &quot;1.2.3&quot;)
                     (function foo :replacement bar)))

;; Remember: do not define the actual function or variable in case of
;; :final deprecation:
(declaim (deprecated :final (&quot;my-system&quot; &quot;1.2.3&quot;)
                     (function fez :replacement whoop)))
</pre></div>

<p>Attempting to use the deprecated functions:
</p><div class="lisp">
<pre class="lisp">(defun baz ()
  (foo))
| STYLE-WARNING: The function CL-USER::FOO has been deprecated...
=&gt; BAZ
(baz)
=&gt; NIL ; no error

(defun danger ()
  (fez))
| WARNING: The function CL-USER::FEZ has been deprecated...
=&gt; DANGER
(danger)
|- ERROR: The function CL-USER::FEZ has been deprecated...
</pre></div>

<hr>
<a name="Deprecated-Interfaces-in-SBCL"></a>
<div class="header">
<p>
Previous: <a href="#Deprecation-Examples" accesskey="p" rel="prev">Deprecation Examples</a>, Up: <a href="#Deprecation" accesskey="u" rel="up">Deprecation</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Deprecated-Interfaces-in-SBCL-1"></a>
<h3 class="section">17.7 Deprecated Interfaces in SBCL</h3>

<p>This sections lists legacy interfaces in various stages of deprecation.
</p>
<a name="List-of-Deprecated-Interfaces"></a>
<h4 class="subsection">17.7.1 List of Deprecated Interfaces</h4>

<a name="Early-Deprecation"></a>
<h4 class="subsubsection">17.7.1.1 Early Deprecation</h4>

<ul>
<li> <strong>SOCKINT::WIN32-*</strong>

<p>Deprecated in favor of the corresponding prefix-less functions
(e.g. <code>sockint::bind</code> replaces <code>sockint::win32-bind</code>) as of
1.2.10 in March 2015. Expected to move into late deprecation in August
2015.
</p>
</li><li> <strong>SB-EXT:QUIT</strong>

<p>Deprecated in favor of <code>sb-ext:exit</code> as of 1.0.56.55 in May 2012.
Expected to move into late deprecation in May 2013.
</p>
<p>The design of <code>sb-ext:quit</code> proved too broken to fix in a
backwards-compatible manner, so it had to be deprecated and replaced.
</p>
<p>Problems with it were manifold: when called in the main thread it
cause the entire process to exit. When called in another thread with
<code>:recklessly-p</code> it also caused the entire process to exit.
However, when called in another thread without <code>:recklessly-p</code> it
instead caused that thread to terminate abnormally without terminating
the process. Its behaviour versus other threads than the one it was
called in was also underspecified, and dependent on things such as the
current session. Any conceivable change that would have made it sane
would also have silently broken code that depended on the old
behaviour.
</p>
<p><strong>Remedy</strong>
</p>
<p>For code needing to work with legacy SBCLs, if you were calling
<code>quit</code> with <code>:recklessly-p t</code>, use
</p>
<br>
<div class="lisp">
<pre class="lisp">(defun system-exit (&amp;optional (code 0))
  (alien-funcall (extern-alien &quot;exit&quot; (function void int)) code))
</pre></div>
<br>

<p>instead. In modern SBCLs simply call either <code>sb-posix:exit</code> or
<code>sb-ext:exit</code>.
</p>
<p>If you were calling it without <code>:recklessly-p</code>, be advised
that your code may not function as expected when called from threads
other than the main one (see above) &ndash; in any case, you can support
legacy SBCLs using the following conditionalization:
</p>
<br>
<div class="lisp">
<pre class="lisp">(defun lisp-exit (&amp;key (code 0) abort)
  #+#.(cl:if (cl:find-symbol &quot;EXIT&quot; :sb-ext) '(and) '(or))
  ;; Assuming process exit is what is desired -- if thread termination
  ;; is intended, use SB-THREAD:ABORT-THREAD instead.
  (sb-ext:exit :code code :abort abort)
  #-#.(cl:if (cl:find-symbol &quot;EXIT&quot; :sb-ext) '(and) '(or))
  (sb-ext:quit :unix-status code :recklessly-p abort))
</pre></div>
<br>

<br>
</li><li> <strong>SB-UNIX:UNIX-EXIT</strong>

<p>Deprecated as of 1.0.56.55 in May 2012. Expected to move into late
deprecation in May 2013.
</p>
<p>When the SBCL process termination was refactored as part of changes that
led to <code>sb-ext:quit</code> being deprecated, <code>sb-unix:unix-exit</code>
ceased to be used internally. Since <code>SB-UNIX</code> is an internal package
not intended for user code to use, and since we&rsquo;re slowly in the process
of refactoring things to be less Unix-oriented, <code>sb-unix:unix-exit</code>
was initially deleted as it was no longer used. Unfortunately it became
apparent that it was used by several external users, so it was re-instated
in deprecated form.
</p>
<p>While the cost of keeping <code>sb-unix:unix-exit</code> indefinitely is
trivial, the ability to refactor our internals is important, so its
deprecation was taken as an opportunity to highlight that
<code>SB-UNIX</code> is an internal package and <code>SB-POSIX</code> should be
used by user-programs instead &ndash; or alternatively calling the foreign
function directly if the desired interface doesn&rsquo;t for some reason
exist in <code>SB-POSIX</code>.
</p>
<p><strong>Remedy</strong>
</p>
<p>For code needing to work with legacy SBCLs, use e.g. <code>system-exit</code>
as show above in remedies for <code>sb-ext:quit</code>. In modern SBCLs
simply call either <code>sb-posix:exit</code> or <code>sb-ext:exit</code> with
appropriate arguments.
</p>
<br>
</li><li> <strong>SB-C::MERGE-TAIL-CALLS Compiler Policy</strong>

<p>Deprecated as of 1.0.53.74 in November 2011. Expected to move into
late deprecation in November 2012.
</p>
<p>This compiler policy was never functional: SBCL has always merged tail
calls when it could, regardless of this policy setting. (It was also
never officially supported, but several code-bases have historically
used it.)
</p>
<p><strong>Remedy</strong>
</p>
<p>Simply remove the policy declarations. They were never necessary: SBCL
always merged tail-calls when possible. To disable tail merging,
structure the code to avoid the tail position instead.
</p>
<br>
</li><li> <strong>Spinlock API</strong>

<p>Deprecated as of 1.0.53.11 in August 2011. Expected to move into late
deprecation in August 2012.
</p>
<p>Spinlocks were an internal interface, but had a number of external users
and were hence deprecated instead of being simply deleted.
</p>
<p>Affected symbols: <code>sb-thread::spinlock</code>,
<code>sb-thread::make-spinlock</code>, <code>sb-thread::with-spinlock</code>,
<code>sb-thread::with-recursive-spinlock</code>,
<code>sb-thread::get-spinlock</code>, <code>sb-thread::release-spinlock</code>,
<code>sb-thread::spinlock-value</code>, and <code>sb-thread::spinlock-name</code>.
</p>
<p><strong>Remedy</strong>
</p>
<p>Use the mutex API instead, or implement spinlocks suiting your needs
on top of <code>sb-ext:compare-and-swap</code>,
<code>sb-ext:spin-loop-hint</code>, etc.
</p>
</li><li> <strong>SOCKINT::HANDLE-&gt;FD</strong>, <strong>SOCKINT::FD-&gt;HANDLE</strong>

<p>Internally deprecated in 2012. Declared deprecated as of 1.2.10 in March
2015. Expected to move into final deprecation in August 2015.
</p>
</li></ul>

<a name="Late-Deprecation"></a>
<h4 class="subsubsection">17.7.1.2 Late Deprecation</h4>

<ul>
<li> <strong>SB-THREAD:JOIN-THREAD-ERROR-THREAD and SB-THREAD:INTERRUPT-THREAD-ERROR-THREAD</strong>

<p>Deprecated in favor of <code>sb-thread:thread-error-thread</code> as of
1.0.29.17 in June 2009. Expected to move into final deprecation in
June 2012.
</p>
<p><strong>Remedy</strong>
</p>
<p>For code that needs to support legacy SBCLs, use e.g.:
</p>
<br>
<div class="lisp">
<pre class="lisp">(defun get-thread-error-thread (condition)
  #+#.(cl:if (cl:find-symbol &quot;THREAD-ERROR-THREAD&quot; :sb-thread)
             '(and) '(or))
  (sb-thread:thread-error-thread condition)
  #-#.(cl:if (cl:find-symbol &quot;THREAD-ERROR-THREAD&quot; :sb-thread)
             '(and) '(or))
  (etypecase condition
   (sb-thread:join-thread-error
    (sb-thread:join-thread-error-thread condition))
   (sb-thread:interrupt-thread-error
    (sb-thread:interrupt-thread-error-thread condition))))
</pre></div>
<br>

<br>
</li><li> <strong>SB-INTROSPECT:FUNCTION-ARGLIST</strong>

<p>Deprecated in favor of <code>sb-introspect:function-lambda-list</code> as of
1.0.24.5 in January 2009. Expected to move into final deprecation in
January 2012.
</p>
<p>Renamed for consistency and aesthetics. Functions have lambda-lists,
not arglists.
</p>
<p><strong>Remedy</strong>
</p>
<p>For code that needs to support legacy SBCLs, use e.g.:
</p>
<br>
<div class="lisp">
<pre class="lisp">(defun get-function-lambda-list (function)
  #+#.(cl:if (cl:find-symbol &quot;FUNCTION-LAMBDA-LIST&quot; :sb-introspect)
             '(and) '(or))
  (sb-introspect:function-lambda-list function)
  #-#.(cl:if (cl:find-symbol &quot;FUNCTION-LAMBDA-LIST&quot; :sb-introspect)
             '(and) '(or))
  (sb-introspect:function-arglist function))
</pre></div>
<br>

<br>
</li><li> <strong>Stack Allocation Policies</strong>

<p>Deprecated in favor of <code>sb-ext:*stack-allocate-dynamic-extent*</code>
as of 1.0.19.7 in August 2008, and are expected to be removed in
August 2012.
</p>
<p>Affected symbols: <code>sb-c::stack-allocate-dynamic-extent</code>,
<code>sb-c::stack-allocate-vector</code>, and
<code>sb-c::stack-allocate-value-cells</code>.
</p>
<p>These compiler policies were never officially supported, and turned
out the be a flawed design.
</p>
<p><strong>Remedy</strong>
</p>
<p>For code that needs stack-allocation in legacy SBCLs, conditionalize
using:
</p>
<br>
<div class="lisp">
<pre class="lisp">#-#.(cl:if (cl:find-symbol &quot;*STACK-ALLOCATE-DYNAMIC-EXTENT*&quot; :sb-ext)
           '(and) '(or))
(declare (optimize sb-c::stack-allocate-dynamic-extent))
</pre></div>
<br>

<p>However, unless stack allocation is essential, we recommend simply
removing these declarations. Refer to documentation on
<code>sb-ext:*stack-allocate-dynamic*</code> for details on stack allocation
control in modern SBCLs.
</p>
<br>
</li><li> <strong>SB-SYS:OUTPUT-RAW-BYTES</strong>

<p>Deprecated as of 1.0.8.16 in June 2007. Expected to move into final
deprecation in June 2012.
</p>
<p>Internal interface with some external users. Never officially
supported, deemed unnecessary in presence of <code>write-sequence</code> and
bivalent streams.
</p>
<p><strong>Remedy</strong>
</p>
<p>Use streams with element-type <code>(unsigned-byte 8)</code>
or <code>:default</code> &ndash; the latter allowing both binary and
character IO &ndash; in conjunction with <code>write-sequence</code>.
</p>
</li></ul>

<a name="Final-Deprecation"></a>
<h4 class="subsubsection">17.7.1.3 Final Deprecation</h4>

<p>No interfaces are currently in final deprecation.
</p>
<a name="Historical-Interfaces"></a>
<h4 class="subsection">17.7.2 Historical Interfaces</h4>

<p>The following is a partial list of interfaces present in historical
versions of SBCL, which have since then been deleted.
</p>
<ul>
<li> <strong>SB-KERNEL:INSTANCE-LAMBDA</strong>

<p>Historically needed for CLOS code. Deprecated as of 0.9.3.32 in August
2005. Deleted as of 1.0.47.8 in April 2011. Plain <code>lambda</code> can be
used where <code>sb-kernel:instance-lambda</code> used to be needed.
</p>
<br>
</li><li> <strong>SB-ALIEN:DEF-ALIEN-ROUTINE, SB-ALIEN:DEF-ALIEN-VARIABLE, SB-ALIEN:DEF-ALIEN-TYPE</strong>

<p>Inherited from CMUCL, naming convention not consistent with preferred
SBCL style. Deprecated as of 0.pre7.90 in December 2001. Deleted as of
1.0.9.17 in September 2007. Replaced by
<code>sb-alien:define-alien-routine</code>,
<code>sb-alien:define-alien-variable</code>, and
<code>sb-alien:define-alien-type</code>.
</p>
</li></ul>
<hr>
<a name="Concept-Index"></a>
<div class="header">
<p>
Next: <a href="#Function-Index" accesskey="n" rel="next">Function Index</a>, Previous: <a href="#Deprecation" accesskey="p" rel="prev">Deprecation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Concept-Index-1"></a>
<h2 class="appendix">Appendix A Concept Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-cp" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Actual-Source">Actual Source</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Parts-of-a-Compiler-Diagnostic">The Parts of a Compiler Diagnostic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Actual-Source-1">Actual Source</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Original-and-Actual-Source">The Original and Actual Source</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Arithmetic_002c-hardware">Arithmetic, hardware</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Modular-arithmetic">Modular arithmetic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Arithmetic_002c-hardware-1">Arithmetic, hardware</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002drotate_002dbyte">sb-rotate-byte</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Arithmetic_002c-modular">Arithmetic, modular</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Modular-arithmetic">Modular arithmetic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Arithmetic_002c-modular-1">Arithmetic, modular</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002drotate_002dbyte">sb-rotate-byte</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Availability-of-debug-variables">Availability of debug variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Value-Availability">Variable Value Availability</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Block-compilation_002c-debugger-implications">Block compilation, debugger implications</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Block_002c-basic">Block, basic</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Source-Location-Availability">Source Location Availability</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Block_002c-start-location">Block, start location</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Source-Location-Availability">Source Location Availability</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Cleanup_002c-stack-frame-kind">Cleanup, stack frame kind</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Code-Coverage">Code Coverage</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Compatibility-with-other-Lisps">Compatibility with other Lisps</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Getting-Existing-Programs-to-Run">Getting Existing Programs to Run</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Compile-time-type-errors">Compile time type errors</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Type-Errors-at-Compile-Time">Type Errors at Compile Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Compiler-Diagnostic-Severity">Compiler Diagnostic Severity</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Compiler-messages">Compiler messages</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Messages">Diagnostic Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Concurrency">Concurrency</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debug-optimization-quality">Debug optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Value-Availability">Variable Value Availability</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debug-optimization-quality-1">Debug optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Source-Location-Availability">Source Location Availability</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debug-optimization-quality-2">Debug optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Policy-Control">Debugger Policy Control</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debug-variables">Debug variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Access">Variable Access</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Debugger">Debugger</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger">Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-debugger_002c-disabling">debugger, disabling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-debugger_002c-enabling">debugger, enabling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-declaration_002c-dynamic_002dextent">declaration, <code>dynamic-extent</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Declarations">Declarations</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Deprecation-Conditions">Deprecation Conditions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Deprecation-Declaration">Deprecation Declaration</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Declaration">Deprecation Declaration</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Deprecation-Examples">Deprecation Examples</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Examples">Deprecation Examples</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disabling-debugger">disabling debugger</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disabling-ldb">disabling ldb</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Runtime-Options">Runtime Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disabling-ldb-1">disabling ldb</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dynamic_002dextent-declaration"><code>dynamic-extent</code> declaration</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Efficiency">Efficiency</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Efficiency">Efficiency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Entry-points_002c-external">Entry points, external</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Errors_002c-run_002dtime">Errors, run-time</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Existing-programs_002c-to-run">Existing programs, to run</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Getting-Existing-Programs-to-Run">Getting Existing Programs to Run</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-External-entry-points">External entry points</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-External-formats">External formats</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Foreign-Type-Specifiers">Foreign Type Specifiers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-External-formats-1">External formats</a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Formats">External Formats</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-External_002c-stack-frame-kind">External, stack frame kind</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Fast-Read-Lock">Fast Read Lock</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Finalization">Finalization</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Foreign-Function-Interface_002c-generation">Foreign Function Interface, generation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dgrovel">sb-grovel</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Frlock">Frlock</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Function_002c-tracing">Function, tracing</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Garbage-collection">Garbage collection</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Garbage-Collection_002c-conservative">Garbage Collection, conservative</a>:</td><td>&nbsp;</td><td valign="top"><a href="#History-and-Implementation-of-SBCL">History and Implementation of SBCL</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Garbage-Collection_002c-generational">Garbage Collection, generational</a>:</td><td>&nbsp;</td><td valign="top"><a href="#History-and-Implementation-of-SBCL">History and Implementation of SBCL</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Gate">Gate</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Hash-tables">Hash tables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Hashing_002c-cryptographic">Hashing, cryptographic</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Inline-expansion">Inline expansion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Open-Coding-and-Inline-Expansion">Open Coding and Inline Expansion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Inline-expansion-1">Inline expansion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Policy-Control">Debugger Policy Control</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Interpreter">Interpreter</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Interpreter">Interpreter</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Interrupts">Interrupts</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Introspecting-Deprecation-Information">Introspecting Deprecation Information</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Introspecting-Deprecation-Information">Introspecting Deprecation Information</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-L">L</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb">ldb</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reporting-Bugs">Reporting Bugs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb-1">ldb</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Runtime-Options">Runtime Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb-2">ldb</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Runtime-Options">Runtime Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb_002c-disabling">ldb, disabling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Runtime-Options">Runtime Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb_002c-disabling-1">ldb, disabling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ldb_002c-enabling">ldb, enabling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Locations_002c-unknown">Locations, unknown</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Logical-pathnames">Logical pathnames</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-Pathnames">Lisp Pathnames</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Macroexpansion">Macroexpansion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Processing-Path">The Processing Path</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Macroexpansion_002c-errors-during">Macroexpansion, errors during</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Errors-During-Macroexpansion">Errors During Macroexpansion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Mailbox_002c-lock_002dfree">Mailbox, lock-free</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Messages_002c-Compiler">Messages, Compiler</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Messages">Diagnostic Messages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Modular-arithmetic">Modular arithmetic</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Modular-arithmetic">Modular arithmetic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Modular-arithmetic-1">Modular arithmetic</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002drotate_002dbyte">sb-rotate-byte</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-O">O</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Open_002dcoding">Open-coding</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Open-Coding-and-Inline-Expansion">Open Coding and Inline Expansion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Operating-System-Interface">Operating System Interface</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dposix">sb-posix</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-optimization-quality_002c-safety">optimization quality, <code>safety</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Optimize-declaration">Optimize declaration</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Policy-Control">Debugger Policy Control</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Optional_002c-stack-frame-kind">Optional, stack frame kind</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Entry-Point-Details">Entry Point Details</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Original-Source">Original Source</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Parts-of-a-Compiler-Diagnostic">The Parts of a Compiler Diagnostic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Original-Source-1">Original Source</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Original-and-Actual-Source">The Original and Actual Source</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Package_002dLocal-Nicknames">Package-Local Nicknames</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Packages_002c-locked">Packages, locked</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Locks">Package Locks</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Pathnames">Pathnames</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Pathnames">Pathnames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Pathnames_002c-logical">Pathnames, logical</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-Pathnames">Lisp Pathnames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Policy_002c-debugger">Policy, debugger</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Policy-Control">Debugger Policy Control</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Posix">Posix</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dposix">sb-posix</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Precise-type-checking">Precise type checking</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Precise-Type-Checking">Precise Type Checking</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Processing-Path">Processing Path</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Parts-of-a-Compiler-Diagnostic">The Parts of a Compiler Diagnostic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Processing-Path-1">Processing Path</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Processing-Path">The Processing Path</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Profiling">Profiling</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Profiling">Profiling</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Profiling_002c-deterministic">Profiling, deterministic</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deterministic-Profiler">Deterministic Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Profiling_002c-statistical">Profiling, statistical</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-Q">Q</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Queue_002c-FIFO">Queue, FIFO</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dqueue">sb-queue</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Queue_002c-lock_002dfree">Queue, lock-free</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Random-Number-Generation">Random Number Generation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Random-Number-Generation">Random Number Generation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Read-errors_002c-compiler">Read errors, compiler</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Read-Errors">Read Errors</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Read_002dEval_002dPrint-Loop">Read-Eval-Print Loop</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002daclrepl">sb-aclrepl</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Reader-Extensions">Reader Extensions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reader-Extensions">Reader Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Recursion_002c-tail">Recursion, tail</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debug-Tail-Recursion">Debug Tail Recursion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-REPL">REPL</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002daclrepl">sb-aclrepl</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Safety-optimization-quality">Safety optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Declarations-as-Assertions">Declarations as Assertions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Safety-optimization-quality-1">Safety optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-safety-optimization-quality"><code>safety</code> optimization quality</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Sb_002dconcurrency">Sb-concurrency</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Semi_002dinline-expansion">Semi-inline expansion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Policy-Control">Debugger Policy Control</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Severity-of-compiler-messages">Severity of compiler messages</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Single-Stepping">Single Stepping</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Slot-access">Slot access</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Slot-access">Slot access</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Sockets_002c-Networking">Sockets, Networking</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Networking">Networking</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Source-location-printing_002c-debugger">Source location printing, debugger</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Source-Location-Printing">Source Location Printing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Source_002dto_002dsource-transformation">Source-to-source transformation</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Processing-Path">The Processing Path</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Stack-frames">Stack frames</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Frames">Stack Frames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Static-functions">Static functions</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Open-Coding-and-Inline-Expansion">Open Coding and Inline Expansion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Stepper">Stepper</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-System-Calls">System Calls</a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dposix">sb-posix</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Tail-recursion">Tail recursion</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debug-Tail-Recursion">Debug Tail Recursion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-The-Deprecation-Pipeline">The Deprecation Pipeline</a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Deprecation-Pipeline">The Deprecation Pipeline</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Tracing">Tracing</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Type-checking_002c-at-compile-time">Type checking, at compile time</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Type-Errors-at-Compile-Time">Type Errors at Compile Time</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Type-checking_002c-precise">Type checking, precise</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Precise-Type-Checking">Precise Type Checking</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Types_002c-portability">Types, portability</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Getting-Existing-Programs-to-Run">Getting Existing Programs to Run</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Unknown-code-locations">Unknown code locations</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Validity-of-debug-variables">Validity of debug variables</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Value-Availability">Variable Value Availability</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Variables_002c-debugger-access">Variables, debugger access</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Access">Variable Access</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Concept-Index_cp_letter-W">W</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-Weak-pointers">Weak pointers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-Why-Deprecate_003f">Why Deprecate?</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Why-Deprecate_003f">Why Deprecate?</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>

<hr>
<a name="Function-Index"></a>
<div class="header">
<p>
Next: <a href="#Variable-Index" accesskey="n" rel="next">Variable Index</a>, Previous: <a href="#Concept-Index" accesskey="p" rel="prev">Concept Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Function-Index-1"></a>
<h2 class="appendix">Appendix B Function Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>(</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_symbol-2"><b>?</b></a>
 &nbsp; 
<br>
<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-fn" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_symbol-1">(</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0028setf"><code>(setf</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0028setf-1"><code>(setf</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0028setf-logical_002dpathname_002dtranslations-_005bcl_005d_0029"><code>(setf logical-pathname-translations [cl])</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-Pathnames">Lisp Pathnames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_0028setf-slot_002dvalue_002dusing_002dclass-_005bsb_002dmop_005d_0029"><code>(setf slot-value-using-class [sb-mop])</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_symbol-2">?</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_003f"><code>?</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-A">A</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-abort"><code>abort</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-abort_002dthread"><code>abort-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-add_002dimplementation_002dpackage"><code>add-implementation-package</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-add_002dpackage_002dlocal_002dnickname"><code>add-package-local-nickname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-addr"><code>addr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Coercing-Foreign-Values">Coercing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-adjust_002dsequence"><code>adjust-sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-adjust_002dsequence-_005bsb_002dsequence_005d"><code>adjust-sequence [sb-sequence]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-age"><code>age</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-alien_002dfuncall"><code>alien-funcall</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-alien_002dfuncall-Primitive">The alien-funcall Primitive</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-alien_002dsap"><code>alien-sap</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Coercing-Foreign-Values">Coercing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-alphabetic_002dp"><code>alphabetic-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-always_002dbound"><code>always-bound</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Global-and-Always_002dBound-variables">Global and Always-Bound variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-array_002dstorage_002dvector"><code>array-storage-vector</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-assert_002dversion_002d_003e_003d"><code>assert-version-&gt;=</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-atomic_002ddecf"><code>atomic-decf</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-atomic_002dincf"><code>atomic-incf</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-atomic_002dpop"><code>atomic-pop</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-atomic_002dpush"><code>atomic-push</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-atomic_002dupdate"><code>atomic-update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-backtrace"><code>backtrace</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-barrier"><code>barrier</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Barriers">Barriers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-bidi_002dclass"><code>bidi-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-bidi_002dmirroring_002dglyph"><code>bidi-mirroring-glyph</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-both_002dcase_002dp-_005bcl_005d"><code>both-case-p [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-bottom"><code>bottom</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Motion">Stack Motion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-bytes_002dconsed_002dbetween_002dgcs"><code>bytes-consed-between-gcs</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-cancel_002dfinalization"><code>cancel-finalization</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cas"><code>cas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-case_002dignorable_002dp"><code>case-ignorable-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cased_002dp"><code>cased-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-casefold"><code>casefold</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cast"><code>cast</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Coercing-Foreign-Values">Coercing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-char_002dblock"><code>char-block</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-char_002ddowncase-_005bcl_005d"><code>char-downcase [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-class_002dname-_005bcl_005d"><code>class-name [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-class_002dof-_005bcl_005d"><code>class-of [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-class_002dprototype-_005bsb_002dmop_005d"><code>class-prototype [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-clear_002dcoverage"><code>clear-coverage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-clear_002dsemaphore_002dnotification"><code>clear-semaphore-notification</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-close"><code>close</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Methods-common-to-all-streams">Methods common to all streams</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-close_002dgate"><code>close-gate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-coerce-_005bcl_005d"><code>coerce [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-combining_002dclass"><code>combining-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-compare_002dand_002dswap"><code>compare-and-swap</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-compute_002deffective_002dmethod-_005bsb_002dmop_005d"><code>compute-effective-method [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-concatenate"><code>concatenate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-condition_002dbroadcast"><code>condition-broadcast</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-condition_002dnotify"><code>condition-notify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-condition_002dwait"><code>condition-wait</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-confusable_002dp"><code>confusable-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-cons-_005bcl_005d"><code>cons [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-continue"><code>continue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-copy-function"><code><code>copy function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-copy_002dseq-_005bcl_005d"><code>copy-seq [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-decimal_002dvalue"><code>decimal-value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-declare-_005bcl_005d"><code>declare [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-default_002dignorable_002dp"><code>default-ignorable-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defcas"><code>defcas</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defclass-_005bcl_005d"><code>defclass [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defclass-_005bcl_005d-1"><code>defclass [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defconstant-_005bcl_005d"><code>defconstant [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Defining-Constants">Defining Constants</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defglobal"><code>defglobal</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Global-and-Always_002dBound-variables">Global and Always-Bound variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-define_002dalien_002droutine"><code>define-alien-routine</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-define_002dalien_002droutine-Macro">The define-alien-routine Macro</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-define_002dalien_002dvariable"><code>define-alien-variable</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Foreign-Variables">External Foreign Variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-define_002dcas_002dexpander"><code>define-cas-expander</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-define_002dhash_002dtable_002dtest"><code>define-hash-table-test</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defmethod-_005bcl_005d"><code>defmethod [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defpackage"><code>defpackage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defpackage-1"><code>defpackage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defpackage-_005bcl_005d"><code>defpackage [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defpackage-_005bcl_005d-1"><code>defpackage [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Implementation-Packages">Implementation Packages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-defstruct-_005bcl_005d"><code>defstruct [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-delete_002ddirectory"><code>delete-directory</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-deprecated"><code>deprecated</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Declaration">Deprecation Declaration</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-deprecated-_005bsb_002dext_005d"><code>deprecated [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Declaration">Deprecation Declaration</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dequeue"><code>dequeue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-deref"><code>deref</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Accessing-Foreign-Values">Accessing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-describe"><code>describe</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-describe_002dcompiler_002dpolicy"><code>describe-compiler-policy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compiler-Policy">Compiler Policy</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-digit_002dvalue"><code>digit-value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disable_002ddebugger"><code>disable-debugger</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disable_002dpackage_002dlocks"><code>disable-package-locks</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-disable_002dpackage_002dlocks-_005bsb_002dext_005d"><code>disable-package-locks [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dolist-_005bcl_005d"><code>dolist [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dosequence"><code>dosequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-down"><code>down</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Motion">Stack Motion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-dynamic_002dspace_002dsize"><code>dynamic-space-size</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-E">E</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-east_002dasian_002dwidth"><code>east-asian-width</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ed"><code>ed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-element-function"><code><code>element function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-elt"><code>elt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-emptyp"><code>emptyp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-enable_002ddebugger"><code>enable-debugger</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Enabling-and-Disabling-the-Debugger">Enabling and Disabling the Debugger</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-enable_002dpackage_002dlocks"><code>enable-package-locks</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-enable_002dpackage_002dlocks-_005bsb_002dext_005d"><code>enable-package-locks [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-endp-function"><code><code>endp function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-enqueue"><code>enqueue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ensure_002dclass-_005bsb_002dmop_005d"><code>ensure-class [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ensure_002dclass_002dusing_002dclass-_005bsb_002dmop_005d"><code>ensure-class-using-class [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-ensure_002dgeneric_002dfunction-_005bcl_005d"><code>ensure-generic-function [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-error"><code>error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-eval-_005bcl_005d"><code>eval [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Interpreter">Interpreter</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-exit"><code>exit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exit">Exit</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-extern_002dalien"><code>extern-alien</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Foreign-Variables">External Foreign Variables</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-file_002ddescriptor"><code>file-descriptor</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#File_002ddescriptors">File-descriptors</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-filename"><code>filename</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Filenames">Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-finalize"><code>finalize</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-finalize_002dinheritance-_005bsb_002dmop_005d"><code>finalize-inheritance [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-find-_005bcl_005d"><code>find [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-find_002dclass-_005bcl_005d"><code>find-class [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-find_002dclass-_005bcl_005d-1"><code>find-class [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-find_002dmethod-_005bcl_005d"><code>find-method [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-flet-_005bcl_005d"><code>flet [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-flet-_005bcl_005d-1"><code>flet [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frame"><code>frame</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Motion">Stack Motion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-free_002dalien"><code>free-alien</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Foreign-Dynamic-Allocation">Foreign Dynamic Allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock_002dname"><code>frlock-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock_002dread"><code>frlock-read</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock_002dread_002dbegin"><code>frlock-read-begin</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock_002dread_002dend"><code>frlock-read-end</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock_002dwrite"><code>frlock-write</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-funcallable_002dstandard_002dinstance_002daccess-_005bsb_002dmop_005d"><code>funcallable-standard-instance-access [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-G">G</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-gate_002dname"><code>gate-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gate_002dopen_002dp"><code>gate-open-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gatep"><code>gatep</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gc"><code>gc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-gc_002dlogfile"><code>gc-logfile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-general_002dcategory"><code>general-category</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002daverage_002dage"><code>generation-average-age</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002dbytes_002dallocated"><code>generation-bytes-allocated</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002dbytes_002dconsed_002dbetween_002dgcs"><code>generation-bytes-consed-between-gcs</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002dminimum_002dage_002dbefore_002dgc"><code>generation-minimum-age-before-gc</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002dnumber_002dof_002dgcs"><code>generation-number-of-gcs</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generation_002dnumber_002dof_002dgcs_002dbefore_002dpromotion"><code>generation-number-of-gcs-before-promotion</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generic_002dfunction_002ddeclarations-_005bsb_002dmop_005d"><code>generic-function-declarations [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dbytes_002dconsed"><code>get-bytes-consed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dcas_002dexpansion"><code>get-cas-expansion</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Atomic-Operations">Atomic Operations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002derrno"><code>get-errno</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Foreign-Variables">External Foreign Variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dhost_002dby_002daddress"><code>get-host-by-address</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Service">Name Service</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dhost_002dby_002dname"><code>get-host-by-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Service">Name Service</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dprotocol_002dby_002dname"><code>get-protocol-by-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#INET-Domain-Sockets">INET Domain Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-get_002dtime_002dof_002dday"><code>get-time-of-day</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-getcwd"><code>getcwd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Functions-with-idiosyncratic-bindings">Functions with idiosyncratic bindings</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-global"><code>global</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Global-and-Always_002dBound-variables">Global and Always-Bound variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-grab_002dfrlock_002dwrite_002dlock"><code>grab-frlock-write-lock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-grab_002dmutex"><code>grab-mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-grapheme_002dbreak_002dclass"><code>grapheme-break-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-graphemes"><code>graphemes</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-H">H</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-hangul_002dsyllable_002dtype"><code>hangul-syllable-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hash_002dtable_002dsynchronized_002dp"><code>hash-table-synchronized-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hash_002dtable_002dweakness"><code>hash-table-weakness</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-help"><code>help</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-hex_002ddigit_002dp"><code>hex-digit-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-host_002dent_002daddress"><code>host-ent-address</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Service">Name Service</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-I">I</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-ideographic_002dp"><code>ideographic-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-index-function"><code><code>index function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-inspect-_005bcl_005d"><code>inspect [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Tools-To-Help-Developers">Tools To Help Developers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-int_002dsap"><code>int-sap</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Accessing-Foreign-Values">Accessing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-intern-_005bcl_005d"><code>intern [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reader-Extensions">Reader Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-intern_002deql_002dspecializer-_005bsb_002dmop_005d"><code>intern-eql-specializer [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-interrupt_002dthread"><code>interrupt-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002dcopy"><code>iterator-copy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002delement"><code>iterator-element</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002dendp"><code>iterator-endp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002dindex"><code>iterator-index</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-iterator_002dstep"><code>iterator-step</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-J">J</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-join_002dthread"><code>join-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-L">L</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-labels-_005bcl_005d"><code>labels [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-labels-_005bcl_005d-1"><code>labels [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-length"><code>length</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-let-_005bcl_005d"><code>let [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Efficiency-Issues">Miscellaneous Efficiency Issues</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-let-_005bcl_005d-1"><code>let [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-let_002a-_005bcl_005d"><code>let* [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Efficiency-Issues">Miscellaneous Efficiency Issues</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-let_002a-_005bcl_005d-1"><code>let* [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-line_002dbreak_002dclass"><code>line-break-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lines"><code>lines</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list-_005bcl_005d"><code>list [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002a-_005bcl_005d"><code>list* [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002dall_002dthreads"><code>list-all-threads</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002dall_002dtimers"><code>list-all-timers</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002dlocals"><code>list-locals</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Access">Variable Access</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002dmailbox_002dmessages"><code>list-mailbox-messages</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list_002dqueue_002dcontents"><code>list-queue-contents</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-load_002dshared_002dobject"><code>load-shared-object</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Loading-Shared-Object-Files">Loading Shared Object Files</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lock_002dpackage"><code>lock-package</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-logand-_005bcl_005d"><code>logand [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Modular-arithmetic">Modular arithmetic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-logical_002dpathname_002dtranslations-_005bcl_005d"><code>logical-pathname-translations [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-Pathnames">Lisp Pathnames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lowercase"><code>lowercase</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-lowercase_002dp"><code>lowercase-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-macrolet-_005bcl_005d"><code>macrolet [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mailbox_002dcount"><code>mailbox-count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mailbox_002dempty_002dp"><code>mailbox-empty-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mailbox_002dname"><code>mailbox-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mailboxp"><code>mailboxp</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-main_002dthread"><code>main-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-main_002dthread_002dp"><code>main-thread-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dalien"><code>make-alien</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Foreign-Dynamic-Allocation">Foreign Dynamic Allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dalien_002dstring"><code>make-alien-string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Foreign-Dynamic-Allocation">Foreign Dynamic Allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002darray-_005bcl_005d"><code>make-array [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dfrlock"><code>make-frlock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dgate"><code>make-gate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dhash_002dtable"><code>make-hash-table</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dinet_002daddress"><code>make-inet-address</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#INET-Domain-Sockets">INET Domain Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dinet6_002daddress"><code>make-inet6-address</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#INET-Domain-Sockets">INET Domain Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dinstance-_005bcl_005d"><code>make-instance [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dmailbox"><code>make-mailbox</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dmethod_002dlambda-_005bsb_002dmop_005d"><code>make-method-lambda [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dmethod_002dspecializers_002dform-_005bsb_002dpcl_005d"><code>make-method-specializers-form [sb-pcl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dmutex"><code>make-mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dqueue"><code>make-queue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsemaphore"><code>make-semaphore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsemaphore_002dnotification"><code>make-semaphore-notification</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsequence_002diterator"><code>make-sequence-iterator</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsequence_002diterator-_005bsb_002dsequence_005d"><code>make-sequence-iterator [sb-sequence]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsequence_002diterator-_005bsb_002dsequence_005d-1"><code>make-sequence-iterator [sb-sequence]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsequence_002dlike"><code>make-sequence-like</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsequence_002dlike-_005bsb_002dsequence_005d"><code>make-sequence-like [sb-sequence]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsimple_002dsequence_002diterator"><code>make-simple-sequence-iterator</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Simple-Iterator-Protocol">Simple Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dsimple_002dsequence_002diterator-_005bsb_002dsequence_005d"><code>make-simple-sequence-iterator [sb-sequence]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dthread"><code>make-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dtimer"><code>make-timer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dwaitqueue"><code>make-waitqueue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-make_002dweak_002dpointer"><code>make-weak-pointer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-map"><code>map</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-math_002dp"><code>math-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-md5sum_002dfile"><code>md5sum-file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-md5sum_002dsequence"><code>md5sum-sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-md5sum_002dstream"><code>md5sum-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-md5sum_002dstring"><code>md5sum-string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-merge"><code>merge</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mirrored_002dp"><code>mirrored-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-muffle_002dconditions"><code>muffle-conditions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Controlling-Verbosity">Controlling Verbosity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mutex_002dname"><code>mutex-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mutex_002downer"><code>mutex-owner</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mutex_002dvalue"><code>mutex-value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-N">N</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-name_002dconflict_002dsymbols-_005bsb_002dext_005d"><code>name-conflict-symbols [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Resolution-of-Name-Conflicts">Resolution of Name Conflicts</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-native_002dnamestring"><code>native-namestring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Native-Filenames">Native Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-native_002dpathname"><code>native-pathname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Native-Filenames">Native Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-next"><code>next</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-non_002dblocking_002dmode"><code>non-blocking-mode</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-normalize_002dstring"><code>normalize-string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-normalized_002dp"><code>normalized-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-numeric_002dvalue"><code>numeric-value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-O">O</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-open-_005bcl_005d"><code>open [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Formats">External Formats</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-open_002dgate"><code>open-gate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-out"><code>out</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-P">P</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dimplemented_002dby_002dlist"><code>package-implemented-by-list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dimplements_002dlist"><code>package-implements-list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocal_002dnicknames"><code>package-local-nicknames</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocally_002dnicknamed_002dby_002dlist"><code>package-locally-nicknamed-by-list</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocked_002derror_002dsymbol"><code>package-locked-error-symbol</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocked_002dp"><code>package-locked-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse_002dnative_002dnamestring"><code>parse-native-namestring</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Native-Filenames">Native Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-parse_002dspecializer_002dusing_002dclass-_005bsb_002dpcl_005d"><code>parse-specializer-using-class [sb-pcl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-posix_002dgetenv"><code>posix-getenv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Querying-the-process-environment">Querying the process environment</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-print"><code>print</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Information-Commands">Information Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dalive_002dp"><code>process-alive-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dclose"><code>process-close</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dcore_002ddumped"><code>process-core-dumped</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002derror"><code>process-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dexit_002dcode"><code>process-exit-code</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dinput"><code>process-input</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dkill"><code>process-kill</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002doutput"><code>process-output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dp"><code>process-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dstatus"><code>process-status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-process_002dwait"><code>process-wait</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-profile"><code>profile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deterministic-Profiler">Deterministic Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-profile_002dcall_002dcounts"><code>profile-call-counts</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-proplist_002dp"><code>proplist-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-purify"><code>purify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Efficiency-Hacks">Efficiency Hacks</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-Q">Q</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-queue_002dcount"><code>queue-count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-queue_002dempty_002dp"><code>queue-empty-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-queue_002dname"><code>queue-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-queuep"><code>queuep</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-R">R</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-readlink"><code>readlink</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Functions-with-idiosyncratic-bindings">Functions with idiosyncratic bindings</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-readtable_002dnormalization"><code>readtable-normalization</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Reader-Extensions">Reader Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-receive_002dmessage"><code>receive-message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-receive_002dmessage_002dno_002dhang"><code>receive-message-no-hang</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-receive_002dpending_002dmessages"><code>receive-pending-messages</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-release_002dfrlock_002dwrite_002dlock"><code>release-frlock-write-lock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-release_002dmutex"><code>release-mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-remove_002dimplementation_002dpackage"><code>remove-implementation-package</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-remove_002dpackage_002dlocal_002dnickname"><code>remove-package-local-nickname</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package_002dLocal-Nicknames">Package-Local Nicknames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-report"><code>report</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deterministic-Profiler">Deterministic Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-report-1"><code>report</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-report-2"><code>report</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-require"><code>require</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-reset"><code>reset</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deterministic-Profiler">Deterministic Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-reset-1"><code>reset</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-reset_002dcoverage"><code>reset-coverage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-restart"><code>restart</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-restart_002dframe"><code>restart-frame</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-restore_002dcoverage"><code>restore-coverage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-restore_002dcoverage_002dfrom_002dfile"><code>restore-coverage-from-file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-restrict_002dcompiler_002dpolicy"><code>restrict-compiler-policy</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compiler-Policy">Compiler Policy</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-return"><code>return</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-return_002dfrom_002dthread"><code>return-from-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rotate_002dbyte"><code>rotate-byte</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002drotate_002dbyte">sb-rotate-byte</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-rotate_002dbyte-_005bsb_002drotate_002dbyte_005d"><code>rotate-byte [sb-rotate-byte]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dmd5">sb-md5</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-run_002dprogram"><code>run-program</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Running-external-programs">Running external programs</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-sap_002dalien"><code>sap-alien</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Coercing-Foreign-Values">Coercing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sap_002dref_002d32"><code>sap-ref-32</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Accessing-Foreign-Values">Accessing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sap_003d"><code>sap=</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Accessing-Foreign-Values">Accessing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-satisfies-_005bcl_005d"><code>satisfies [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Handling-of-Types">Handling of Types</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-save_002dcoverage"><code>save-coverage</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-save_002dcoverage_002din_002dfile"><code>save-coverage-in-file</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dcover">sb-cover</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-save_002dlisp_002dand_002ddie"><code>save-lisp-and-die</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Saving-a-Core-Image">Saving a Core Image</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-schedule_002dtimer"><code>schedule-timer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-script"><code>script</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-seed_002drandom_002dstate"><code>seed-random-state</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Random-Number-Generation">Random Number Generation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-semaphore_002dcount"><code>semaphore-count</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-semaphore_002dname"><code>semaphore-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-semaphore_002dnotification_002dstatus"><code>semaphore-notification-status</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-send_002dmessage"><code>send-message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sentence_002dbreak_002dclass"><code>sentence-break-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sentences"><code>sentences</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-set_002dsbcl_002dsource_002dlocation"><code>set-sbcl-source-location</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-Pathnames">Lisp Pathnames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-setf-element-function"><code><code>setf element function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-setf-_005bcl_005d"><code>setf [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Efficiency-Issues">Miscellaneous Efficiency Issues</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-setq-_005bcl_005d"><code>setq [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Efficiency-Issues">Miscellaneous Efficiency Issues</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-signal_002dsemaphore"><code>signal-semaphore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-slot"><code>slot</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Accessing-Foreign-Values">Accessing Foreign Values</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-slot_002dboundp_002dusing_002dclass-_005bsb_002dmop_005d"><code>slot-boundp-using-class [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-slot_002ddefinition_002dname-_005bsb_002dmop_005d"><code>slot-definition-name [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-slot_002dvalue_002dusing_002dclass-_005bsb_002dmop_005d"><code>slot-value-using-class [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002daccept"><code>socket-accept</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dbind"><code>socket-bind</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dclose"><code>socket-close</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dconnect"><code>socket-connect</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002derror"><code>socket-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dlisten"><code>socket-listen</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dmake_002dstream"><code>socket-make-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dmake_002dstream-1"><code>socket-make-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dname"><code>socket-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dopen_002dp"><code>socket-open-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dpeername"><code>socket-peername</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dreceive"><code>socket-receive</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dsend"><code>socket-send</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket_002dshutdown"><code>socket-shutdown</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dbroadcast"><code>sockopt-broadcast</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dbsd_002dcompatible"><code>sockopt-bsd-compatible</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002ddebug"><code>sockopt-debug</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002ddont_002droute"><code>sockopt-dont-route</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dkeep_002dalive"><code>sockopt-keep-alive</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002doob_002dinline"><code>sockopt-oob-inline</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dpass_002dcredentials"><code>sockopt-pass-credentials</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dreuse_002daddress"><code>sockopt-reuse-address</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sockopt_002dtcp_002dnodelay"><code>sockopt-tcp-nodelay</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Socket-Options">Socket Options</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-soft_002ddotted_002dp"><code>soft-dotted-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-source"><code>source</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Source-Location-Printing">Source Location Printing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-standard_002dinstance_002daccess-_005bsb_002dmop_005d"><code>standard-instance-access [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-start"><code>start</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-start_002dprofiling"><code>start-profiling</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-step"><code>step</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-step-1"><code>step</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-step-function"><code><code>step function</code></code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stop"><code>stop</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Single-Stepping">Single Stepping</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stop_002dprofiling"><code>stop-profiling</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dadvance_002dto_002dcolumn"><code>stream-advance-to-column</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dclear_002dinput"><code>stream-clear-input</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-stream-methods">Input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dclear_002doutput"><code>stream-clear-output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Output-stream-methods">Output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002delement_002dtype"><code>stream-element-type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Methods-common-to-all-streams">Methods common to all streams</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dexternal_002dformat-_005bcl_005d"><code>stream-external-format [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Formats">External Formats</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dfile_002dposition"><code>stream-file-position</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Methods-common-to-all-streams">Methods common to all streams</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dfinish_002doutput"><code>stream-finish-output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Output-stream-methods">Output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dforce_002doutput"><code>stream-force-output</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Output-stream-methods">Output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dfresh_002dline"><code>stream-fresh-line</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dline_002dcolumn"><code>stream-line-column</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dline_002dlength"><code>stream-line-length</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dlisten"><code>stream-listen</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dpeek_002dchar"><code>stream-peek-char</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dread_002dbyte"><code>stream-read-byte</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary-stream-methods">Binary stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dread_002dchar"><code>stream-read-char</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dread_002dchar_002dno_002dhang"><code>stream-read-char-no-hang</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dread_002dline"><code>stream-read-line</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dread_002dsequence"><code>stream-read-sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Input-stream-methods">Input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dstart_002dline_002dp"><code>stream-start-line-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dterpri"><code>stream-terpri</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dunread_002dchar"><code>stream-unread-char</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-input-stream-methods">Character input stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dwrite_002dbyte"><code>stream-write-byte</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Binary-stream-methods">Binary stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dwrite_002dchar"><code>stream-write-char</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dwrite_002dsequence"><code>stream-write-sequence</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Output-stream-methods">Output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stream_002dwrite_002dstring"><code>stream-write-string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Character-output-stream-methods">Character output stream methods</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-string_002dupcase-_005bcl_005d"><code>string-upcase [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-subseq-_005bcl_005d"><code>subseq [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-subseq-_005bcl_005d-1"><code>subseq [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-subseq-_005bcl_005d-2"><code>subseq [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-subtypep-_005bcl_005d"><code>subtypep [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002dmacrolet-_005bcl_005d"><code>symbol-macrolet [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002dvalue_002din_002dthread"><code>symbol-value-in-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-syslog"><code>syslog</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Functions-with-idiosyncratic-bindings">Functions with idiosyncratic bindings</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-terminate_002dthread"><code>terminate-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread_002dalive_002dp"><code>thread-alive-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread_002derror_002dthread"><code>thread-error-thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread_002dname"><code>thread-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread_002dyield"><code>thread-yield</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-timer_002dname"><code>timer-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-timer_002dscheduled_002dp"><code>timer-scheduled-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-titlecase"><code>titlecase</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-top"><code>top</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Motion">Stack Motion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-toplevel"><code>toplevel</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Exiting-Commands">Exiting Commands</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-trace"><code>trace</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-trace-_005bcl_005d"><code>trace [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Tools-To-Help-Developers">Tools To Help Developers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-truly_002dthe"><code>truly-the</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Efficiency-Hacks">Efficiency Hacks</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-try_002dsemaphore"><code>try-semaphore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-typep-_005bcl_005d"><code>typep [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-U">U</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_002d1_002dname"><code>unicode-1-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_002dequal"><code>unicode-equal</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_003c"><code>unicode&lt;</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_003c_003d"><code>unicode&lt;=</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_003d"><code>unicode=</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_003e"><code>unicode&gt;</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unicode_003e_003d"><code>unicode&gt;=</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unload_002dshared_002dobject"><code>unload-shared-object</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Loading-Shared-Object-Files">Loading Shared Object Files</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unlock_002dpackage"><code>unlock-package</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unmuffle_002dconditions"><code>unmuffle-conditions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Controlling-Verbosity">Controlling Verbosity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unparse_002dspecializer_002dusing_002dclass-_005bsb_002dpcl_005d"><code>unparse-specializer-using-class [sb-pcl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unprofile"><code>unprofile</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deterministic-Profiler">Deterministic Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unprofile_002dcall_002dcounts"><code>unprofile-call-counts</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-unschedule_002dtimer"><code>unschedule-timer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-untrace"><code>untrace</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-up"><code>up</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Stack-Motion">Stack Motion</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-uppercase"><code>uppercase</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-uppercase_002dp"><code>uppercase-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-V">V</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-validate_002dsuperclass-_005bsb_002dmop_005d"><code>validate-superclass [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-validate_002dsuperclass-_005bsb_002dmop_005d-1"><code>validate-superclass [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-var"><code>var</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Variable-Access">Variable Access</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-vector-_005bcl_005d"><code>vector [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Function-Index_fn_letter-W">W</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-wait_002dfor"><code>wait-for</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-Extensions">Miscellaneous Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-wait_002don_002dgate"><code>wait-on-gate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-wait_002don_002dsemaphore"><code>wait-on-semaphore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-waitqueue_002dname"><code>waitqueue-name</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-weak_002dpointer_002dvalue"><code>weak-pointer-value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-whitespace_002dp"><code>whitespace-p</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dalien"><code>with-alien</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Local-Foreign-Variables">Local Foreign Variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dcompilation_002dunit"><code>with-compilation-unit</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Compiler-Policy">Compiler Policy</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dcompilation_002dunit-_005bcl_005d"><code>with-compilation-unit [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#The-Parts-of-a-Compiler-Diagnostic">The Parts of a Compiler Diagnostic</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dlocked_002dhash_002dtable"><code>with-locked-hash-table</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-Table-Extensions">Hash Table Extensions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dmutex"><code>with-mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dopen_002dfile-_005bcl_005d"><code>with-open-file [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#External-Formats">External Formats</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dprofiling"><code>with-profiling</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002drecursive_002dlock"><code>with-recursive-lock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dsampling"><code>with-sampling</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dsequence_002diterator"><code>with-sequence-iterator</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dsequence_002diterator_002dfunctions"><code>with-sequence-iterator-functions</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-with_002dunlocked_002dpackages"><code>with-unlocked-packages</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-without_002dpackage_002dlocks"><code>without-package-locks</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-word_002dbreak_002dclass"><code>word-break-class</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-words"><code>words</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Unicode-Support">Unicode Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>(</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_symbol-2"><b>?</b></a>
 &nbsp; 
<br>
<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-U"><b>U</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>

<hr>
<a name="Variable-Index"></a>
<div class="header">
<p>
Next: <a href="#Type-Index" accesskey="n" rel="next">Type Index</a>, Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Variable-Index-1"></a>
<h2 class="appendix">Appendix C Variable Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Variable-Index_vr_symbol-1"><b>*</b></a>
 &nbsp; 
<a class="summary-letter" href="#Variable-Index_vr_symbol-2"><b>+</b></a>
</td></tr></table>
<table class="index-vr" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Variable-Index_vr_symbol-1">*</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aafter_002dgc_002dhooks_002a"><code>*after-gc-hooks*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002acompiler_002dprint_002dvariable_002dalist_002a"><code>*compiler-print-variable-alist*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Controlling-Verbosity">Controlling Verbosity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002acore_002dpathname_002a"><code>*core-pathname*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Saving-a-Core-Image">Saving a Core Image</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002acurrent_002dthread_002a"><code>*current-thread*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002adebug_002dprint_002dvariable_002dalist_002a"><code>*debug-print-variable-alist*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Command-Loop">Debugger Command Loop</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aed_002dfunctions_002a"><code>*ed-functions*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aevaluator_002dmode_002a"><code>*evaluator-mode*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Interpreter">Interpreter</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aevaluator_002dmode_002a-_005bsb_002dext_005d"><code>*evaluator-mode* [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Interpreter">Interpreter</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aexit_002dhooks_002a"><code>*exit-hooks*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Initialization-and-Exit-Hooks">Initialization and Exit Hooks</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002agc_002drun_002dtime_002a"><code>*gc-run-time*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Garbage-Collection">Garbage Collection</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002ainit_002dhooks_002a"><code>*init-hooks*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Initialization-and-Exit-Hooks">Initialization and Exit Hooks</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002ainvoke_002ddebugger_002dhook_002a"><code>*invoke-debugger-hook*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Debugger-Invocation">Debugger Invocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002amax_002dsamples_002a"><code>*max-samples*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002amax_002dtrace_002dindentation_002a"><code>*max-trace-indentation*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002amodule_002dprovider_002dfunctions_002a"><code>*module-provider-functions*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002amuffled_002dwarnings_002a"><code>*muffled-warnings*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Customization-Hooks-for-Users">Customization Hooks for Users</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aon_002dpackage_002dvariance_002a"><code>*on-package-variance*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Variance">Package Variance</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002apackage_002a-_005bcl_005d"><code>*package* [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Implementation-Packages">Implementation Packages</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aposix_002dargv_002a-_005bsb_002dext_005d"><code>*posix-argv* [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Shebang-Scripts">Shebang Scripts</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002aposix_002dargv_002a-_005bsb_002dext_005d-1"><code>*posix-argv* [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Command_002dline-arguments">Command-line arguments</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002asample_002dinterval_002a"><code>*sample-interval*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Statistical-Profiler">Statistical Profiler</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002asave_002dhooks_002a"><code>*save-hooks*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Saving-a-Core-Image">Saving a Core Image</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002astack_002dallocate_002ddynamic_002dextent_002a"><code>*stack-allocate-dynamic-extent*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Dynamic_002dextent-allocation">Dynamic-extent allocation</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002asysinit_002dpathname_002dfunction_002a"><code>*sysinit-pathname-function*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Saving-a-Core-Image">Saving a Core Image</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002atrace_002dencapsulate_002ddefault_002a"><code>*trace-encapsulate-default*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002atrace_002dindentation_002dstep_002a"><code>*trace-indentation-step*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Function-Tracing">Function Tracing</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002auserinit_002dpathname_002dfunction_002a"><code>*userinit-pathname-function*</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Saving-a-Core-Image">Saving a Core Image</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Variable-Index_vr_symbol-2">+</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-_002bslot_002dunbound_002b-_005bsb_002dpcl_005d"><code>+slot-unbound+ [sb-pcl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Variable-Index_vr_symbol-1"><b>*</b></a>
 &nbsp; 
<a class="summary-letter" href="#Variable-Index_vr_symbol-2"><b>+</b></a>
</td></tr></table>

<hr>
<a name="Type-Index"></a>
<div class="header">
<p>
Next: <a href="#Colophon" accesskey="n" rel="next">Colophon</a>, Previous: <a href="#Variable-Index" accesskey="p" rel="prev">Variable Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Type-Index-1"></a>
<h2 class="appendix">Appendix D Type Index</h2>

<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Type-Index_tp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>
<table class="index-tp" border="0">
<tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-B">B</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-built_002din_002dclass-_005bcl_005d"><code>built-in-class [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-C">C</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-code_002ddeletion_002dnote"><code>code-deletion-note</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-code_002ddeletion_002dnote-_005bsb_002dext_005d"><code>code-deletion-note [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-compiler_002dnote"><code>compiler-note</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-compiler_002dnote-_005bsb_002dext_005d"><code>compiler-note [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-D">D</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-deprecation_002dcondition"><code>deprecation-condition</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-deprecation_002derror"><code>deprecation-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-E">E</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-early_002ddeprecation_002dwarning"><code>early-deprecation-warning</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-error-_005bcl_005d"><code>error [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-F">F</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-file_002ddescriptor-1"><code>file-descriptor</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#File_002ddescriptors">File-descriptors</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-file_002ddescriptor_002ddesignator"><code>file-descriptor-designator</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#File_002ddescriptors">File-descriptors</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-filename-1"><code>filename</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Filenames">Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-filename_002ddesignator"><code>filename-designator</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Filenames">Filenames</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-final_002ddeprecation_002dwarning"><code>final-deprecation-warning</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-flock"><code>flock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-objects-and-C-structures">Lisp objects and C structures</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-frlock"><code>frlock</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-funcallable_002dstandard_002dclass-_005bsb_002dmop_005d"><code>funcallable-standard-class [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-funcallable_002dstandard_002dobject-_005bsb_002dmop_005d"><code>funcallable-standard-object [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-funcallable_002dstandard_002dobject-_005bsb_002dmop_005d-1"><code>funcallable-standard-object [sb-mop]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-function-_005bcl_005d"><code>function [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-function-_005bcl_005d-1"><code>function [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dbinary_002dinput_002dstream"><code>fundamental-binary-input-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dbinary_002doutput_002dstream"><code>fundamental-binary-output-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dbinary_002dstream"><code>fundamental-binary-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dcharacter_002dinput_002dstream"><code>fundamental-character-input-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dcharacter_002doutput_002dstream"><code>fundamental-character-output-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dcharacter_002dstream"><code>fundamental-character-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dinput_002dstream"><code>fundamental-input-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002doutput_002dstream"><code>fundamental-output-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-fundamental_002dstream"><code>fundamental-stream</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Gray-Streams-classes">Gray Streams classes</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-G">G</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-gate"><code>gate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-generic_002dfunction-_005bcl_005d"><code>generic-function [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-H">H</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-host_002dent"><code>host-ent</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Name-Service">Name Service</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-I">I</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-inet_002dsocket"><code>inet-socket</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#INET-Domain-Sockets">INET Domain Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-inet6_002dsocket"><code>inet6-socket</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#INET-Domain-Sockets">INET Domain Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-interrupt_002dthread_002derror"><code>interrupt-thread-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-J">J</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-join_002dthread_002derror"><code>join-thread-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-L">L</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-late_002ddeprecation_002dwarning"><code>late-deprecation-warning</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Deprecation-Conditions">Deprecation Conditions</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-list-_005bcl_005d-1"><code>list [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-local_002dsocket"><code>local-socket</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Local-_0028Unix_0029-Domain-Sockets">Local (Unix) Domain Sockets</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-M">M</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-mailbox"><code>mailbox</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-mutex"><code>mutex</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Mutex-Support">Mutex Support</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-N">N</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-name_002dconflict-_005bsb_002dext_005d"><code>name-conflict [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Resolution-of-Name-Conflicts">Resolution of Name Conflicts</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-P">P</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002derror-_005bcl_005d"><code>package-error [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlock_002dviolation"><code>package-lock-violation</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlock_002dviolation-_005bsb_002dext_005d"><code>package-lock-violation [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocked_002derror"><code>package-locked-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-package_002dlocked_002derror-_005bsb_002dext_005d"><code>package-locked-error [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-passwd"><code>passwd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-objects-and-C-structures">Lisp objects and C structures</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-protocol_002dunimplemented"><code>protocol-unimplemented</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-Q">Q</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-queue"><code>queue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#sb_002dconcurrency">sb-concurrency</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-S">S</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-semaphore"><code>semaphore</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-semaphore_002dnotification"><code>semaphore-notification</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Semaphores">Semaphores</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sequence-_005bcl_005d"><code>sequence [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sequence-_005bcl_005d-1"><code>sequence [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sequence-_005bcl_005d-2"><code>sequence [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-sequence-_005bcl_005d-3"><code>sequence [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Iterator-Protocol">Iterator Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-socket"><code>socket</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#General-Sockets">General Sockets</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-standard_002dclass-_005bcl_005d"><code>standard-class [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-standard_002dgeneric_002dfunction-_005bcl_005d"><code>standard-generic-function [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-standard_002dobject-_005bcl_005d"><code>standard-object [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-standard_002dobject-_005bcl_005d-1"><code>standard-object [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-stat"><code>stat</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-objects-and-C-structures">Lisp objects and C structures</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-structure_002dclass-_005bcl_005d"><code>structure-class [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-style_002dwarning-_005bcl_005d"><code>style-warning [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002dpackage_002dlocked_002derror"><code>symbol-package-locked-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Dictionary">Package Lock Dictionary</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-symbol_002dpackage_002dlocked_002derror-_005bsb_002dext_005d"><code>symbol-package-locked-error [sb-ext]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Package-Lock-Violations">Package Lock Violations</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-T">T</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-t-_005bcl_005d"><code>t [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Metaobject-Protocol">Metaobject Protocol</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-termios"><code>termios</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-objects-and-C-structures">Lisp objects and C structures</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread"><code>thread</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-thread_002derror"><code>thread-error</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Threading-basics">Threading basics</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-timer"><code>timer</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Timers">Timers</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-timeval"><code>timeval</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Lisp-objects-and-C-structures">Lisp objects and C structures</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-V">V</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-vector-_005bcl_005d-1"><code>vector [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Extensible-Sequences">Extensible Sequences</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
<tr><th><a name="Type-Index_tp_letter-W">W</a></th><td></td><td></td></tr>
<tr><td></td><td valign="top"><a href="#index-waitqueue"><code>waitqueue</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Waitqueue_002fcondition-variables">Waitqueue/condition variables</a></td></tr>
<tr><td></td><td valign="top"><a href="#index-warning-_005bcl_005d"><code>warning [cl]</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Diagnostic-Severity">Diagnostic Severity</a></td></tr>
<tr><td colspan="4"> <hr></td></tr>
</table>
<table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Type-Index_tp_letter-B"><b>B</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-D"><b>D</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-E"><b>E</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-G"><b>G</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-H"><b>H</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-I"><b>I</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-J"><b>J</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-L"><b>L</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-M"><b>M</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-N"><b>N</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-Q"><b>Q</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-T"><b>T</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-V"><b>V</b></a>
 &nbsp; 
<a class="summary-letter" href="#Type-Index_tp_letter-W"><b>W</b></a>
 &nbsp; 
</td></tr></table>

<hr>
<a name="Colophon"></a>
<div class="header">
<p>
Previous: <a href="#Type-Index" accesskey="p" rel="prev">Type Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<a name="Colophon-1"></a>
<h2 class="unnumbered">Colophon</h2>

<p>This manual is maintained in Texinfo, and automatically translated
into other forms (e.g. HTML or pdf). If you&rsquo;re <em>reading</em> this
manual in one of these non-Texinfo translated forms, that&rsquo;s fine, but
if you want to <em>modify</em> 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 <em>the</em>
Texinfo version (maintained at the time of this writing as part of the
SBCL project at <a href="http://sbcl.sourceforge.net/">http://sbcl.sourceforge.net/</a>) and submit a
patch.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>

<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
<p>Historically, the ILISP package at
<a href="http://ilisp.cons.org/">http://ilisp.cons.org/</a> provided similar functionality, but it
does not support modern SBCL versions.</p>
<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3>
<p>Actually, this declaration is unnecessary in
SBCL, since it already knows that <code>position</code> returns a
non-negative <code>fixnum</code> or <code>nil</code>.</p>
<h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
<p>A deprecated
extension <code>sb-ext:inhibit-warnings</code> is still supported, but
liable to go away at any time.</p>
<h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
<p>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.  See <a href="#Unknown-Locations-and-Interrupts">Unknown Locations and Interrupts</a>.</p>
<h3><a name="FOOT5" href="#DOCF5">(5)</a></h3>
<p>The variable bindings are actually created
using the Lisp <code>symbol-macrolet</code> special form.</p>
<h3><a name="FOOT6" href="#DOCF6">(6)</a></h3>
<p>A motivation, rationale and additional examples for the design
of this extension can be found in the paper <cite>Rhodes, Christophe
(2007): User-extensible sequences in Common Lisp</cite> available for download
at
<a href="http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf">http://www.doc.gold.ac.uk/~mas01cr/papers/ilc2007/sequences-20070301.pdf</a>.</p>
<h3><a name="FOOT7" href="#DOCF7">(7)</a></h3>
<p>In SBCL versions prior to 1.0.13, <code>sb-ext:run-program</code>
searched for executables in a manner somewhat incompatible with other
languages.  As of this version, SBCL uses the system library routine
<code>execvp(3)</code>, and no longer contains the function,
<code>find-executable-in-search-path</code>, which implemented the old
search.  Users who need this function may find it
in <samp>run-program.lisp</samp> versions 1.67 and earlier in SBCL&rsquo;s CVS
repository here
<a href="http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log">http://sbcl.cvs.sourceforge.net/sbcl/sbcl/src/code/run-program.lisp?view=log</a>. However,
we caution such users that this search routine finds executables that
system library routines do not.</p>
<h3><a name="FOOT8" href="#DOCF8">(8)</a></h3>
<p>Please
note that the codepoint U+1F5CF (PAGE) introduced in Unicode 7.0 is
named <code>UNICODE_PAGE</code>, since the name &ldquo;Page&rdquo; is required to be
assigned to form-feed (U+0C) by the ANSI standard.</p>
<h3><a name="FOOT9" href="#DOCF9">(9)</a></h3>
<p>See chapter 7 &quot;Testing widely used RNGs&quot; in
<cite>TestU01: A C Library for Empirical Testing of Random Number
Generators</cite> by Pierre L&rsquo;Ecuyer and Richard Simard, ACM Transactions on
Mathematical Software, Vol. 33, article 22, 2007.</p>
<h3><a name="FOOT10" href="#DOCF10">(10)</a></h3>
<p>The functionality contained in the package
<code>SB-UNIX</code> is for SBCL internal use only; its contents are likely to
change from version to version.</p>
<h3><a name="FOOT11" href="#DOCF11">(11)</a></h3>
<p>See &ldquo;namespace&rdquo; entry in the glossary
of the Common Lisp Hyperspec.</p>
</div>
<hr>



</body>
</html>
sbcl-doc 2:1.3.14-2 / usr / share / doc / sbcl-doc / html / sbcl.html
