Changeset 8704


Ignore:
Timestamp:
Mar 10, 2008, 11:40:33 PM (11 years ago)
Author:
mikel
Message:

added discussion of gcable records

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/source/doc/src/ffi.xml

    r8703 r8704  
    11<?xml version="1.0" encoding="utf-8"?>
    22<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    3 <!ENTITY rest "<varname>&amp;rest</varname>">
    4 <!ENTITY key "<varname>&amp;key</varname>">
    5 <!ENTITY optional "<varname>&amp;optional</varname>">
    6 <!ENTITY body "<varname>&amp;body</varname>">
    7 <!ENTITY aux "<varname>&amp;aux</varname>">
    8 <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
    9 <!ENTITY CCL "<literal>CCL</literal>">
    10 ]>
     3          <!ENTITY rest "<varname>&amp;rest</varname>">
     4          <!ENTITY key "<varname>&amp;key</varname>">
     5          <!ENTITY optional "<varname>&amp;optional</varname>">
     6          <!ENTITY body "<varname>&amp;body</varname>">
     7          <!ENTITY aux "<varname>&amp;aux</varname>">
     8          <!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
     9          <!ENTITY CCL "<literal>CCL</literal>">
     10          ]>
    1111
    1212<chapter id="The-Foreign-Function-Interface">
    1313  <title>The Foreign-Function Interface</title>
    1414 
     15  <!-- ******************************************  -->
    1516  <sect1 id="Specifying-And-Using-Foreign-Types">
    1617    <title>Specifying And Using Foreign Types</title>
     
    5657    </sect2>
    5758
    58       <sect2 id="Syntax-of-Foreign-Type-Specifiers">
    59         <title>Syntax of Foreign Type Specifiers</title>
    60         <itemizedlist>
    61           <listitem>
    62             <para>Some foreign types are builtin: keywords denote
     59    <sect2 id="Syntax-of-Foreign-Type-Specifiers">
     60      <title>Syntax of Foreign Type Specifiers</title>
     61      <itemizedlist>
     62        <listitem>
     63          <para>Some foreign types are builtin: keywords denote
    6364            primitive,builtin types such as the IEEE-double-float type
    6465            (denoted:DOUBLE-FLOAT), in much the same way as certain
    6566            symbols(CONS, FIXNUM,etc.) define primitive CL
    6667            types.</para>
    67           </listitem>
    68           <listitem>
    69             <para>Constructors such as :SIGNED and :UNSIGNED can be
     68        </listitem>
     69        <listitem>
     70          <para>Constructors such as :SIGNED and :UNSIGNED can be
    7071            used to denotesigned and unsigned integer subtypes
    7172            (analogous to the CL typespecifiers SIGNED-BYTE and
    7273            UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
    7374            :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
    74           </listitem>
    75           <listitem>
    76             <para>Aliases for other (perhaps more complicated) types
     75        </listitem>
     76        <listitem>
     77          <para>Aliases for other (perhaps more complicated) types
    7778            can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
    7879            CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
    7980            defined as an alias for (:SIGNED8) on some platforms, as
    8081            (:UNSIGNED 8) on others.</para>
    81           </listitem>
    82           <listitem>
    83             <para>The construct (:STRUCT <emphasis>name</emphasis>)
    84             can be used torefer to a named structure type; (:UNION
    85             <emphasis>name</emphasis>)can be used to refer to a named
    86             union type. It isn't necessary toenumerate a structure or
    87             union type's fields in order to refer tothe type.</para>
    88           </listitem>
    89           <listitem>
    90             <para>If <emphasis>X</emphasis> is a valid foreign type
    91             reference,then (:* <emphasis>X</emphasis>) denotes the
    92             foreign type "pointerto<emphasis> X</emphasis>". By
    93             convention, (:* T) denotes ananonymous pointer type,
    94             vaguely equivalent to "void*" in C.</para>
    95           </listitem>
    96           <listitem>
    97             <para>If a fieldlist is a list of lists, each of whose CAR
    98             is a foreign field name (keyword) and whose CADR is a
    99             foreign type specifier, then (:STRUCT
    100             <emphasis>name</emphasis> ,@fieldlist) is adefinition of
    101             the structure type <emphasis>name</emphasis>,
    102             and (:UNION<emphasis> name</emphasis> ,@fieldlist) is a
    103             definition of theunion type
    104             <emphasis>name</emphasis>. Note that it's necessary
    105             todefine a structure or union type in order to include
    106             that type in a structure, union, or array, but only
    107             necessary to "refer to" a strucure or union type in order
    108             to define a type alias or a pointer type.</para>
    109           </listitem>
    110           <listitem>
    111             <para>If <emphasis>X</emphasis> is a defined foreign type
    112             , then (:array <emphasis>X</emphasis> &amp;rest dims)
    113             denotes the foreigntype "array of
    114             <emphasis>X</emphasis>". Although multiplearray dimensions
    115             are allowed by the :array constructor,
    116             only single-dimensioned arrays are (at all) well-supported
    117             in &CCL;.</para>
    118           </listitem>
    119         </itemizedlist>
    120       </sect2>
    121     </sect1>
    122 
    123     <sect1 id="Foreign-Function-Calls">
    124       <title>Foreign Function Calls</title>
    125 
    126       <sect2 id="Overview-foreign-calls">
    127         <title>Overview</title>
    128         <para>&CCL; provides a number of constructs for calling
     82            </listitem>
     83        <listitem>
     84              <para>The construct (:STRUCT <emphasis>name</emphasis>)
     85                can be used torefer to a named structure type; (:UNION
     86                <emphasis>name</emphasis>)can be used to refer to a named
     87                union type. It isn't necessary toenumerate a structure or
     88                union type's fields in order to refer tothe type.</para>
     89            </listitem>
     90        <listitem>
     91              <para>If <emphasis>X</emphasis> is a valid foreign type
     92                reference,then (:* <emphasis>X</emphasis>) denotes the
     93                foreign type "pointerto<emphasis> X</emphasis>". By
     94                convention, (:* T) denotes ananonymous pointer type,
     95                vaguely equivalent to "void*" in C.</para>
     96            </listitem>
     97        <listitem>
     98              <para>If a fieldlist is a list of lists, each of whose CAR
     99                is a foreign field name (keyword) and whose CADR is a
     100                foreign type specifier, then (:STRUCT
     101                <emphasis>name</emphasis> ,@fieldlist) is adefinition of
     102                the structure type <emphasis>name</emphasis>,
     103                and (:UNION<emphasis> name</emphasis> ,@fieldlist) is a
     104                definition of theunion type
     105                <emphasis>name</emphasis>. Note that it's necessary
     106                todefine a structure or union type in order to include
     107                that type in a structure, union, or array, but only
     108                necessary to "refer to" a strucure or union type in order
     109                to define a type alias or a pointer type.</para>
     110            </listitem>
     111            <listitem>
     112              <para>If <emphasis>X</emphasis> is a defined foreign type
     113                , then (:array <emphasis>X</emphasis> &amp;rest dims)
     114                denotes the foreigntype "array of
     115                <emphasis>X</emphasis>". Although multiplearray dimensions
     116                are allowed by the :array constructor,
     117                only single-dimensioned arrays are (at all) well-supported
     118                in &CCL;.</para>
     119            </listitem>
     120      </itemizedlist>
     121    </sect2>
     122  </sect1>
     123
     124  <!-- ******************************************  -->
     125  <sect1 id="Foreign-Function-Calls">
     126    <title>Foreign Function Calls</title>
     127
     128    <sect2 id="Overview-foreign-calls">
     129          <title>Overview</title>
     130      <para>&CCL; provides a number of constructs for calling
    129131        foreign functions from Lisp code (all of them based on the
    130132        function CCL:%FF-CALL).  In many cases, &CCL;'s interface
     
    134136        which may be more concise and/or more readable than other
    135137        constructs.</para>
    136         <para>&CCL; also provides a mechanism for defining
     138      <para>&CCL; also provides a mechanism for defining
    137139        <emphasis>callbacks</emphasis>: lisp functions which can be
    138140        called from foreign code.</para>
    139         <para>There's no supported way to directly pass lisp data to
     141      <para>There's no supported way to directly pass lisp data to
    140142        foreign functions: scalar lisp data must be coerced to an
    141143        equivalent foreign representatation, and lisp arrays (notably
    142144        strings) must be copied to non-GCed memory.</para>
    143145
    144         <sect3 id="Type-Designators-for-Arguments-and-Return-Values">
    145           <title>Type Designators for Arguments and Return Values</title>
    146           <para>The types of foreign argument and return values in foreign
    147           function calls and callbacks can be specified by any of the following
    148 keywords:</para>
    149           <variablelist>
    150             <varlistentry>
    151               <term>:UNSIGNED-BYTE</term>
    152 
    153               <listitem>
    154                 <para>The argument/return value is of type (UNSIGNED-BYTE 8)</para>
    155               </listitem>
    156             </varlistentry>
    157 
    158             <varlistentry>
    159               <term>:SIGNED-BYTE</term>
    160 
    161               <listitem>
    162                 <para>The argument/return value is of type (SIGNED-BYTE 8)</para>
    163               </listitem>
    164             </varlistentry>
    165 
    166             <varlistentry>
    167               <term>:UNSIGNED-HALFWORD</term>
    168 
    169               <listitem>
    170                 <para>The argument/return value is of type (UNSIGNED-BYTE 16)</para>
    171               </listitem>
    172             </varlistentry>
    173 
    174             <varlistentry>
    175               <term>:SIGNED-HALFWORD</term>
    176 
    177               <listitem>
    178                 <para>The argument/return value is of type (SIGNED-BYTE 16)</para>
    179               </listitem>
    180             </varlistentry>
    181 
    182             <varlistentry>
    183               <term>:UNSIGNED-FULLWORD</term>
    184 
    185               <listitem>
    186                 <para>The argument/return value is of type (UNSIGNED-BYTE 32)</para>
    187               </listitem>
    188             </varlistentry>
    189 
    190             <varlistentry>
    191               <term>:SIGNED-FULLWORD</term>
    192 
    193               <listitem>
    194                 <para>The argument/return value is of type (SIGNED-BYTE 32)</para>
    195               </listitem>
    196             </varlistentry>
    197 
    198             <varlistentry>
    199               <term>:UNSIGNED-DOUBLEWORD</term>
    200 
    201               <listitem>
    202                 <para>The argument/return value is of type (UNSIGNED-BYTE 64)</para>
    203               </listitem>
    204             </varlistentry>
    205 
    206             <varlistentry>
    207               <term>:SIGNED-DOUBLEWORD</term>
    208 
    209               <listitem>
    210                 <para>The argument/return value is of type (SIGNED-BYTE 64)</para>
    211               </listitem>
    212             </varlistentry>
    213 
    214             <varlistentry>
    215               <term>:SINGLE-FLOAT</term>
    216 
    217               <listitem>
    218                 <para>The argument/return value is of type SINGLE-FLOAT</para>
    219               </listitem>
    220             </varlistentry>
    221 
    222             <varlistentry>
    223               <term>:DOUBLE-FLOAT</term>
    224 
    225               <listitem>
    226                 <para>The argument/return value is of type DOUBLE-FLOAT</para>
    227               </listitem>
    228             </varlistentry>
    229 
    230             <varlistentry>
    231               <term>:ADDRESS</term>
    232 
    233               <listitem>
    234                 <para>The argument/return values
    235                 is <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
    236               </listitem>
    237             </varlistentry>
    238 
    239             <varlistentry>
    240               <term>:VOID</term>
    241 
    242               <listitem>
    243                 <para>or NIL Not valid as an argument type specifier; specifies
    244                 that there is no meaningful return value</para>
    245               </listitem>
    246             </varlistentry>
    247           </variablelist>
    248 
    249           <para>On some platforms, a small positive integer
     146      <sect3 id="Type-Designators-for-Arguments-and-Return-Values">
     147            <title>Type Designators for Arguments and Return Values</title>
     148        <para>The types of foreign argument and return values in foreign
     149              function calls and callbacks can be specified by any of the following
     150          keywords:</para>
     151            <variablelist>
     152              <varlistentry>
     153                <term>:UNSIGNED-BYTE</term>
     154
     155                <listitem>
     156                      <para>The argument/return value is of type (UNSIGNED-BYTE 8)</para>
     157                </listitem>
     158              </varlistentry>
     159
     160              <varlistentry>
     161                <term>:SIGNED-BYTE</term>
     162
     163                <listitem>
     164                      <para>The argument/return value is of type (SIGNED-BYTE 8)</para>
     165                </listitem>
     166              </varlistentry>
     167
     168              <varlistentry>
     169                <term>:UNSIGNED-HALFWORD</term>
     170
     171                <listitem>
     172                      <para>The argument/return value is of type (UNSIGNED-BYTE 16)</para>
     173                </listitem>
     174              </varlistentry>
     175
     176              <varlistentry>
     177                <term>:SIGNED-HALFWORD</term>
     178
     179                <listitem>
     180                      <para>The argument/return value is of type (SIGNED-BYTE 16)</para>
     181                </listitem>
     182              </varlistentry>
     183
     184              <varlistentry>
     185                <term>:UNSIGNED-FULLWORD</term>
     186
     187                <listitem>
     188                      <para>The argument/return value is of type (UNSIGNED-BYTE 32)</para>
     189                </listitem>
     190              </varlistentry>
     191
     192              <varlistentry>
     193                <term>:SIGNED-FULLWORD</term>
     194
     195                <listitem>
     196                      <para>The argument/return value is of type (SIGNED-BYTE 32)</para>
     197                </listitem>
     198              </varlistentry>
     199
     200              <varlistentry>
     201                <term>:UNSIGNED-DOUBLEWORD</term>
     202
     203                <listitem>
     204                      <para>The argument/return value is of type (UNSIGNED-BYTE 64)</para>
     205                </listitem>
     206              </varlistentry>
     207
     208              <varlistentry>
     209                <term>:SIGNED-DOUBLEWORD</term>
     210
     211                <listitem>
     212                      <para>The argument/return value is of type (SIGNED-BYTE 64)</para>
     213                </listitem>
     214              </varlistentry>
     215
     216              <varlistentry>
     217                <term>:SINGLE-FLOAT</term>
     218
     219                <listitem>
     220                      <para>The argument/return value is of type SINGLE-FLOAT</para>
     221                </listitem>
     222              </varlistentry>
     223
     224              <varlistentry>
     225                <term>:DOUBLE-FLOAT</term>
     226
     227                <listitem>
     228                      <para>The argument/return value is of type DOUBLE-FLOAT</para>
     229                </listitem>
     230              </varlistentry>
     231
     232              <varlistentry>
     233                <term>:ADDRESS</term>
     234
     235                <listitem>
     236                      <para>The argument/return values
     237                        is <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
     238                </listitem>
     239              </varlistentry>
     240
     241              <varlistentry>
     242                <term>:VOID</term>
     243
     244                <listitem>
     245                      <para>or NIL Not valid as an argument type specifier; specifies
     246                        that there is no meaningful return value</para>
     247                </listitem>
     248              </varlistentry>
     249            </variablelist>
     250
     251        <para>On some platforms, a small positive integer
    250252          <emphasis>N</emphasis> can also be used as an argument
    251253          specifier; it indicates that the corresponding argument is a
     
    253255          which should be passed by value to the foreign
    254256          function.  Exactly which foreign structures are passed
    255           by value and how is very dependent on the Application
    256           Binary Interface (ABI) of the platform; unless you're
    257           very familar with ABI detatils (some of which are quite
    258           baroque), it's often easier to let higher-level constructs
    259           deal with these details.</para>
    260         </sect3>
    261 
    262         <sect3 id="External-Entrypoints-and-Named-External-Entrypoints">
    263           <title>External Entrypoints and Named External Entrypoints</title>
    264           <para>PowerPC machine instructions are always aligned on
     257              by value and how is very dependent on the Application
     258              Binary Interface (ABI) of the platform; unless you're
     259              very familar with ABI detatils (some of which are quite
     260              baroque), it's often easier to let higher-level constructs
     261              deal with these details.</para>
     262      </sect3>
     263
     264      <sect3 id="External-Entrypoints-and-Named-External-Entrypoints">
     265            <title>External Entrypoints and Named External Entrypoints</title>
     266        <para>PowerPC machine instructions are always aligned on
    265267          32-bit boundaries, so the two least significant bits of the
    266268          first instruction ("entrypoint") of a foreign function are
     
    272274          address. An entrypoint address can also be encapsulated in a
    273275          MACPTR (see FIXTHIS), but that's somewhat less efficient.</para>
    274           <para>Although it's possible to use fixnums or macptrs to
     276        <para>Although it's possible to use fixnums or macptrs to
    275277          represent entrypoint addresses, it's somewhat cumbersome to
    276278          do so. &CCL; can cache the addresses of named external
     
    281283          indirection allows &CCL; runtime system to ensure that the
    282284          EEP's address is current and correct.</para>
    283         </sect3>
    284       </sect2>
    285 
    286       <sect2 id="Return-Conventions-for-C-Structures">
    287         <title>Return Conventions for C Structures</title>
    288         <para> On some platforms, C functions that are defined to
     285      </sect3>
     286    </sect2>
     287
     288    <sect2 id="Return-Conventions-for-C-Structures">
     289          <title>Return Conventions for C Structures</title>
     290      <para> On some platforms, C functions that are defined to
    289291        return structures do so by reference: they actually
    290292        accept a first parameter of type "pointer to returned
    291293        struct/union" - which must be allocated by the caller - and
    292294        don't return a meaningful value.</para>
    293         <para><emphasis>Exactly</emphasis> how a C function that's
    294         defined to return a foreign structure does so is dependent on
    295         the ABI (and on the size ad composition of the structure/union
    296         in many cases.)</para>
    297       </sect2>
    298     </sect1>
    299 
    300     <sect1 id="Referencing-and-Using-Foreign-Memory-Addresses">
    301       <title>Referencing and Using Foreign Memory Addresses</title>
    302 
    303       <sect2 id="Overview-memory-addresses">
    304         <title>Overview</title>
    305 
    306         <sect3 id="Basics">
    307           <title>Basics</title>
    308           <para>For a variety of technical reasons, it isn't generally
     295          <para><emphasis>Exactly</emphasis> how a C function that's
     296            defined to return a foreign structure does so is dependent on
     297            the ABI (and on the size ad composition of the structure/union
     298            in many cases.)</para>
     299    </sect2>
     300  </sect1>
     301
     302  <!-- ******************************************  -->
     303  <sect1 id="Referencing-and-Using-Foreign-Memory-Addresses">
     304    <title>Referencing and Using Foreign Memory Addresses</title>
     305
     306    <sect2 id="Overview-memory-addresses">
     307      <title>Overview</title>
     308
     309      <sect3 id="Basics">
     310            <title>Basics</title>
     311        <para>For a variety of technical reasons, it isn't generally
    309312          possible to directly reference arbitrary absolute addresses
    310313          (such as those returned by the C library function malloc(),
     
    315318          to provide a way of referring to an underlying "raw"
    316319          address.</para>
    317           <para>It's sometimes convenient to blur the distinction
     320        <para>It's sometimes convenient to blur the distinction
    318321          between a MACPTR and the address it represents; it's
    319322          sometimes necessary to maintain that distiction. It's
     
    324327          anything to do with the lifetime of the block of memory its
    325328          address points to.</para>
    326           <para>It might be tempting to ask "How does one obtain the
     329        <para>It might be tempting to ask "How does one obtain the
    327330          address encapsulated by a MACPTR ?". The answer to that
    328331          question is that one doesn't do that (and there's no way to
    329332          do that): addresses aren't first-class objects, and there's
    330333          no way to refer to one.</para>
    331           <para>Two MACPTRs that encapsulate the same address are EQL
     334        <para>Two MACPTRs that encapsulate the same address are EQL
    332335          to each other.</para>
    333           <para>There are a small number of ways to directly create a
     336        <para>There are a small number of ways to directly create a
    334337          MACPTR (and there's a fair amount of syntactic sugar built
    335338          on top of of those primitives.) These primitives will be
    336339          discussed in greater detail below, but they include:</para>
    337340
    338           <itemizedlist>
    339             <listitem>
    340             <para>Creating a MACPTR with a specified address, usually
    341             via thefunction CCL:%INT-TO-PTR.</para>
    342             </listitem>
    343             <listitem>
    344               <para>Referencing the return valueof a foreign function
    345               call (see )that's specified to return an address.</para>
    346             </listitem>
    347             <listitem>
    348               <para>Referencing a memory location that's specified to
    349               contain an address.</para>
    350             </listitem>
    351           </itemizedlist>
    352 
    353           <para>All of these primitive MACPTR-creating operations are
     341            <itemizedlist>
     342          <listitem>
     343                <para>Creating a MACPTR with a specified address, usually
     344                  via thefunction CCL:%INT-TO-PTR.</para>
     345              </listitem>
     346          <listitem>
     347                <para>Referencing the return valueof a foreign function
     348                  call (see )that's specified to return an address.</para>
     349              </listitem>
     350          <listitem>
     351                <para>Referencing a memory location that's specified to
     352                  contain an address.</para>
     353              </listitem>
     354            </itemizedlist>
     355
     356        <para>All of these primitive MACPTR-creating operations are
    354357          usually open-coded by the compiler; it has a fairly good
    355358          notion of what low-level operations "produce" MACPTRs and
     
    357360          encapsulate, and will usually optimize out the introduction
    358361          of intermediate MACPTRs in a simple expression.</para>
    359           <para>One consequence of the use of MACPTR objects to
     362        <para>One consequence of the use of MACPTR objects to
    360363          encapsulate foreign addresses is that (naively)
    361364          <emphasis>every reference to a foreign address causes a
    362           MACPTR to be allocated.</emphasis></para>
    363           <para>Consider a code fragment like the following:</para>
    364           <programlisting>
     365            MACPTR to be allocated.</emphasis></para>
     366        <para>Consider a code fragment like the following:</para>
     367        <programlisting>
    365368(defun get-next-event ()
    366369  "get the next event from a hypothetical window system"
    367370  (loop
    368     (let* ((event (#_get_next_window_system_event))) ; via an FF-CALL
    369           (unless (null-event-p event)
    370             (handle-event event)))))
    371 </programlisting>
    372           <para>As this is written, each call to the (hypothetical)
     371     (let* ((event (#_get_next_window_system_event))) ; via an FF-CALL
     372       (unless (null-event-p event)
     373         (handle-event event)))))
     374        </programlisting>
     375        <para>As this is written, each call to the (hypothetical)
    373376          foreign function #_get_next_window_system_event will return
    374377          a new MACPTR object.  Ignoring for the sake of argument the
     
    379382          Clearly, the "naive" approach is impractical in many
    380383          cases.</para>
    381         </sect3>
    382 
    383         <sect3 id="Stack-allocation-of---and-destructive-operations-on---MACPTRs-">
    384           <title>Stack allocation of - and destructive operations on - MACPTRs.</title>
    385           <para>If certain conditions held in the environment in which
    386           GET-NEXT-EVENT ran - namely, if it was guaranteed that
    387           neither NULL-EVENT-P nor HANDLE-EVENT cached or otherwise
    388           retained their arguments (the "event" pointer) - there'd be
    389           a few alternatives to the naive approach. One of those
    390           approaches would be to use the primitive function
    391           %SETF-MACPTR (described in greater detail below) to
    392           destructively modify a MACPTR (to change the value of the
    393           address it encapsulates.) The GET-NEXT-EVENT example could
    394           be re-written as:</para>
    395           <programlisting>
     384      </sect3>
     385
     386      <sect3 id="Stack-allocation-of---and-destructive-operations-on---MACPTRs-">
     387        <title>Stack allocation of - and destructive operations on - MACPTRs.</title>
     388            <para>If certain conditions held in the environment in which
     389              GET-NEXT-EVENT ran - namely, if it was guaranteed that
     390              neither NULL-EVENT-P nor HANDLE-EVENT cached or otherwise
     391              retained their arguments (the "event" pointer) - there'd be
     392              a few alternatives to the naive approach. One of those
     393              approaches would be to use the primitive function
     394              %SETF-MACPTR (described in greater detail below) to
     395              destructively modify a MACPTR (to change the value of the
     396              address it encapsulates.) The GET-NEXT-EVENT example could
     397              be re-written as:</para>
     398        <programlisting>
    396399(defun get-next-event ()
    397   (let* ((event (%int-to-ptr 0))) ; create a MACPTR with address 0
     400  (let* ((event (%int-to-ptr 0)))     ; create a MACPTR with address 0
    398401    (loop
    399       (%setf-macptr event (#_get_next_window_system_event)) ; re-use it
    400       (unless (null-event-p event)
    401         (handle-event event)))))
    402 </programlisting>
    403           <para>That version's a bit more realistic: it allocates a
     402       (%setf-macptr event (#_get_next_window_system_event)) ; re-use it
     403       (unless (null-event-p event)
     404         (handle-event event)))))
     405        </programlisting>
     406        <para>That version's a bit more realistic: it allocates a
    404407          single MACPTR outside if the loop, then changes its address
    405408          to point to the current address of the hypothetical event
     
    408411          a million times fewer MACPTRs per call; that sounds like a
    409412          Good Thing.</para>
    410           <para>An Even Better Thing would be to advise the compiler
     413        <para>An Even Better Thing would be to advise the compiler
    411414          that the initial value (the null MACPTR) bound to the
    412415          variable event has dynamic extent (that value won't be
     
    421424          cost), we could move the binding back inside the
    422425          loop:</para>
    423           <programlisting>
    424 (defun get-next-event ()
    425   (loop
    426     (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0)
    427       (declare (dynamic-extent event))
    428       (%setf-macptr event (#_get_next_window_system_event))
    429       (unless (null-event-p event)
    430         (handle-event event)))))
    431 </programlisting>
    432           <para>The idiom of binding one or more variables to
     426        <programlisting>
     427          (defun get-next-event ()
     428          (loop
     429          (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0)
     430          (declare (dynamic-extent event))
     431          (%setf-macptr event (#_get_next_window_system_event))
     432          (unless (null-event-p event)
     433          (handle-event event)))))
     434        </programlisting>
     435        <para>The idiom of binding one or more variables to
    433436          stack-allocated MACPTRs, then destructively modifying those
    434437          MACPTRs before executing a body of code is common enough
     
    437440          GET-NEXT-EVENT is semantically equivalent to the previous
    438441          version, but hopefully a bit more concise:</para>
    439           <programlisting>
     442        <programlisting>
    440443(defun get-next-event ()
    441444  (loop
    442     (with-macptrs ((event (#_get_next_window_system_event)))
    443       (unless (null-event-p event)
    444         (handle-event event)))))
    445 </programlisting>
    446         </sect3>
    447 
    448         <sect3 id="Stack-allocated-memory--and-stack-allocated-pointers-to-it--">
    449           <title>Stack-allocated memory (and stack-allocated pointers to it.)</title>
    450           <para>Fairly often, the blocks of foreign memory (obtained
    451           by malloc or something similar) have well-defined lifetimes
    452           (they can safely be freed at some point when it's known that
    453           they're no longer needed and it's known that they're no
    454           longer referenced.) A common idiom might be:</para>
    455           <programlisting>
     445     (with-macptrs ((event (#_get_next_window_system_event)))
     446       (unless (null-event-p event)
     447         (handle-event event)))))
     448        </programlisting>
     449      </sect3>
     450
     451      <sect3 id="Stack-allocated-memory--and-stack-allocated-pointers-to-it--">
     452        <title>Stack-allocated memory (and stack-allocated pointers to it.)</title>
     453            <para>Fairly often, the blocks of foreign memory (obtained
     454              by malloc or something similar) have well-defined lifetimes
     455              (they can safely be freed at some point when it's known that
     456              they're no longer needed and it's known that they're no
     457              longer referenced.) A common idiom might be:</para>
     458        <programlisting>
    456459(with-macptrs (p (#_allocate_foreign_memory size))
    457460  (unwind-protect
    458     (use-foreign-memory p)
     461       (use-foreign-memory p)
    459462    (#_deallocate_foreign_memory p)))
    460 </programlisting>
    461           <para>That's not unreasonable code, but it's fairly
     463        </programlisting>
     464        <para>That's not unreasonable code, but it's fairly
    462465          expensive for a number of reasons: foreign functions calls
    463466          are themselves fairly expensive (as is UNWIND-PROTECT), and
     
    465468          foreign memory (things like malloc and free) can be fairly
    466469          expensive in their own right.</para>
    467           <para>In the idiomatic code above, both the MACPTR P and the
     470        <para>In the idiomatic code above, both the MACPTR P and the
    468471          block of memory that's being allocated and freed have
    469472          dynamic extent and are therefore good candidates for stack
     
    473476          stack-allocated blocks of foreign memory. Using
    474477          %STACK-BLOCK, the idiomatic code is:</para>
    475           <programlisting>
     478        <programlisting>
    476479(%stack-block ((p size))
    477   (use-foreign-memory p))
    478 </programlisting>
    479           <para>which is a bit more efficient and a bit more concise
     480              (use-foreign-memory p))
     481        </programlisting>
     482        <para>which is a bit more efficient and a bit more concise
    480483          than the version presented earlier.</para>
    481           <para>%STACK-BLOCK is used as the basis for slightly
     484        <para>%STACK-BLOCK is used as the basis for slightly
    482485          higher-level things like RLET. (See FIXTHIS for more information
    483486          about RLET.)</para>
    484         </sect3>
    485 
    486         <sect3 id="Caveats-">
    487           <title>Caveats.</title>
    488           <para>Reading from, writing to, allocating, and freeing
     487      </sect3>
     488
     489      <sect3 id="Caveats-">
     490            <title>Caveats.</title>
     491        <para>Reading from, writing to, allocating, and freeing
    489492          foreign memory are all potentially dangerous operations;
    490493          this is no less true when these operations are performed in
     
    496499          is reliable and safe; slightly incorrect use of these
    497500          constructs and primitives can crash &CCL;.</para>
    498         </sect3>
    499       </sect2>
    500 
    501       <sect2 id="Foreign-Memory-Addresses-Dictionary">
    502         <title>Foreign-Memory-Addresses Dictionary</title>
    503         <para>Unless otherwise noted, all of the symbols mentioned
     501      </sect3>
     502    </sect2>
     503
     504    <sect2 id="Foreign-Memory-Addresses-Dictionary">
     505          <title>Foreign-Memory-Addresses Dictionary</title>
     506      <para>Unless otherwise noted, all of the symbols mentioned
    504507        below are exported from the CCL package.</para>
    505508
    506         <sect3 id="Scalar-memory-reference">
    507           <title>Scalar memory reference</title>
    508           <variablelist>
    509             <varlistentry>
    510               <term>Syntax</term>
    511 
    512               <listitem>
    513                 <para>%get-signed-byte ptr &#38;optional (offset 0)</para>
    514 
    515                 <para>%get-unsigned-byte ptr &#38;optional (offset 0)</para>
    516 
    517                 <para>%get-signed-word ptr &#38;optional (offset 0)</para>
    518 
    519                 <para>%get-unsigned-word ptr &#38;optional (offset 0)</para>
    520 
    521                 <para>%get-signed-long ptr &#38;optional (offset 0)</para>
    522 
    523                 <para>%get-unsigned-long ptr &#38;optional (offset 0)</para>
    524 
    525                 <para>%%get-signed-longlong ptr &#38;optional (offset 0)</para>
    526 
    527                 <para>%%get-unsigned-longlong ptr &#38;optional (offset 0)</para>
    528 
    529                 <para>%get-ptr ptr &#38;optional (offset 0)</para>
    530 
    531                 <para>%get-single-float ptr &#38;optional (offset 0)</para>
    532 
    533                 <para>%get-double-float ptr &#38;optional (offset 0)</para>
    534               </listitem>
    535             </varlistentry>
    536             <varlistentry>
    537               <term>Description</term>
    538 
    539               <listitem>
    540                 <para>References and returns the signed or unsigned 8-bit byte,
    541                 signed or unsigned 16-bit word, signed or unsigned 32-bit long
    542                 word, signed or unsigned 64-bit long long word, 32-bit address,
    543                 32-bit single-float, or 64-bit double-float at the effective byte
    544                 address formed by adding offset to the address encapsulated by
    545                 ptr.</para>
    546               </listitem>
    547             </varlistentry>
    548 
    549             <varlistentry>
    550               <term>Arguments</term>
    551 
    552               <listitem>
    553 
    554                 <variablelist>
    555                   <varlistentry>
    556                     <term>ptr</term>
    557 
    558                     <listitem>
     509      <sect3 id="Scalar-memory-reference">
     510        <title>Scalar memory reference</title>
     511            <variablelist>
     512              <varlistentry>
     513                <term>Syntax</term>
     514
     515                <listitem>
     516                      <para>%get-signed-byte ptr &#38;optional (offset 0)</para>
     517
     518                      <para>%get-unsigned-byte ptr &#38;optional (offset 0)</para>
     519
     520                      <para>%get-signed-word ptr &#38;optional (offset 0)</para>
     521
     522                      <para>%get-unsigned-word ptr &#38;optional (offset 0)</para>
     523
     524                      <para>%get-signed-long ptr &#38;optional (offset 0)</para>
     525
     526                      <para>%get-unsigned-long ptr &#38;optional (offset 0)</para>
     527
     528                      <para>%%get-signed-longlong ptr &#38;optional (offset 0)</para>
     529
     530                      <para>%%get-unsigned-longlong ptr &#38;optional (offset 0)</para>
     531
     532                      <para>%get-ptr ptr &#38;optional (offset 0)</para>
     533
     534                      <para>%get-single-float ptr &#38;optional (offset 0)</para>
     535
     536                      <para>%get-double-float ptr &#38;optional (offset 0)</para>
     537                </listitem>
     538              </varlistentry>
     539              <varlistentry>
     540                <term>Description</term>
     541
     542                <listitem>
     543                      <para>References and returns the signed or unsigned 8-bit byte,
     544                        signed or unsigned 16-bit word, signed or unsigned 32-bit long
     545                        word, signed or unsigned 64-bit long long word, 32-bit address,
     546                        32-bit single-float, or 64-bit double-float at the effective byte
     547                        address formed by adding offset to the address encapsulated by
     548                        ptr.</para>
     549                </listitem>
     550              </varlistentry>
     551
     552              <varlistentry>
     553                <term>Arguments</term>
     554
     555                <listitem>
     556
     557                      <variablelist>
     558                        <varlistentry>
     559                          <term>ptr</term>
     560
     561                          <listitem>
     562                            <para>A MACPTR</para>
     563                          </listitem>
     564                        </varlistentry>
     565
     566                        <varlistentry>
     567                          <term>offset</term>
     568
     569                          <listitem>
     570                            <para>A fixnum</para>
     571                          </listitem>
     572                        </varlistentry>
     573                      </variablelist>
     574                </listitem>
     575              </varlistentry>
     576            </variablelist>
     577
     578        <para>All of the memory reference primitives described above can be</para>
     579        <para>used with SETF.</para>
     580      </sect3>
     581
     582      <sect3 id="iget-bit--Function-">
     583            <title>%get-bit [Function]</title>
     584
     585            <variablelist>
     586              <varlistentry>
     587                <term>Syntax</term>
     588
     589                <listitem>
     590                      <para>%get-bit ptr bit-offset</para>
     591                </listitem>
     592              </varlistentry>
     593
     594              <varlistentry>
     595                <term>Description</term>
     596
     597                <listitem>
     598                      <para>References and returns the bit-offsetth bit at the address
     599                        encapsulated by ptr. (Bit 0 at a given address is the most
     600                        significant bit of the byte at that address.) Can be used with
     601                        SETF.</para>
     602                </listitem>
     603              </varlistentry>
     604
     605              <varlistentry>
     606                <term>Arguments</term>
     607
     608                <listitem>
     609                      <para>&#x00A0;</para>
     610
     611                      <variablelist>
     612                        <varlistentry>
     613                          <term>ptr</term>
     614
     615                          <listitem>
     616                            <para>A MACPTR</para>
     617                          </listitem>
     618                        </varlistentry>
     619
     620                        <varlistentry>
     621                          <term>bit-offset</term>
     622
     623                          <listitem>
     624                            <para>A fixnum</para>
     625                          </listitem>
     626                        </varlistentry>
     627                      </variablelist>
     628                </listitem>
     629              </varlistentry>
     630            </variablelist>
     631      </sect3>
     632
     633      <sect3 id="iget-bitfield--Function-">
     634        <title>%get-bitfield [Function]</title>
     635            <variablelist>
     636              <varlistentry>
     637                <term>Syntax</term>
     638
     639                <listitem>
     640                      <para>%get-bitfield ptr bit-offset width</para>
     641                </listitem>
     642              </varlistentry>
     643
     644              <varlistentry>
     645                <term>Description</term>
     646
     647                <listitem>
     648                      <para>References and returns an unsigned integer composed from the
     649                        width bits found bit-offsetbits from the address encapsulated by
     650                        ptr. (The least significant bit of the result is the value of
     651                        (%get-bit ptr (1- (+ bit-offset width))). Can be used with SETF.</para>
     652                </listitem>
     653              </varlistentry>
     654
     655              <varlistentry>
     656                <term>Arguments</term>
     657
     658                <listitem>
     659                      <para>&#x00A0;</para>
     660                </listitem>
     661              </varlistentry>
     662
     663              <varlistentry>
     664                <term>ptr</term>
     665
     666                <listitem>
    559667                      <para>A MACPTR</para>
    560                     </listitem>
    561                   </varlistentry>
    562 
    563                   <varlistentry>
    564                     <term>offset</term>
    565 
    566                     <listitem>
    567                       <para>A fixnum</para>
    568                     </listitem>
    569                   </varlistentry>
    570                 </variablelist>
    571               </listitem>
    572             </varlistentry>
    573           </variablelist>
    574 
    575           <para>All of the memory reference primitives described above can be</para>
    576           <para>used with SETF.</para>
    577         </sect3>
    578 
    579         <sect3 id="iget-bit--Function-">
    580           <title>%get-bit [Function]</title>
    581 
    582           <variablelist>
    583             <varlistentry>
    584               <term>Syntax</term>
    585 
    586               <listitem>
    587                 <para>%get-bit ptr bit-offset</para>
    588               </listitem>
    589             </varlistentry>
    590 
    591             <varlistentry>
    592               <term>Description</term>
    593 
    594               <listitem>
    595                 <para>References and returns the bit-offsetth bit at the address
    596                 encapsulated by ptr. (Bit 0 at a given address is the most
    597                 significant bit of the byte at that address.) Can be used with
    598                 SETF.</para>
    599               </listitem>
    600             </varlistentry>
    601 
    602             <varlistentry>
    603               <term>Arguments</term>
    604 
    605               <listitem>
    606                 <para>&#x00A0;</para>
    607 
    608                 <variablelist>
    609                   <varlistentry>
    610                     <term>ptr</term>
    611 
    612                     <listitem>
    613                       <para>A MACPTR</para>
    614                     </listitem>
    615                   </varlistentry>
    616 
    617                   <varlistentry>
    618                     <term>bit-offset</term>
    619 
    620                     <listitem>
    621                       <para>A fixnum</para>
    622                     </listitem>
    623                   </varlistentry>
    624                 </variablelist>
    625               </listitem>
    626             </varlistentry>
    627           </variablelist>
    628         </sect3>
    629 
    630         <sect3 id="iget-bitfield--Function-">
    631           <title>%get-bitfield [Function]</title>
    632           <variablelist>
    633             <varlistentry>
    634               <term>Syntax</term>
    635 
    636               <listitem>
    637                 <para>%get-bitfield ptr bit-offset width</para>
    638               </listitem>
    639             </varlistentry>
    640 
    641             <varlistentry>
    642               <term>Description</term>
    643 
    644               <listitem>
    645                 <para>References and returns an unsigned integer composed from the
    646                 width bits found bit-offsetbits from the address encapsulated by
    647                 ptr. (The least significant bit of the result is the value of
    648                 (%get-bit ptr (1- (+ bit-offset width))). Can be used with SETF.</para>
    649               </listitem>
    650             </varlistentry>
    651 
    652             <varlistentry>
    653               <term>Arguments</term>
    654 
    655               <listitem>
    656                 <para>&#x00A0;</para>
    657               </listitem>
    658             </varlistentry>
    659 
    660             <varlistentry>
    661               <term>ptr</term>
    662 
    663               <listitem>
    664                 <para>A MACPTR</para>
    665 
    666                 <variablelist>
    667                   <varlistentry>
    668                     <term>bit-offset</term>
    669 
    670                     <listitem>
    671                       <para>A fixnum</para>
    672                     </listitem>
    673                   </varlistentry>
    674 
    675                   <varlistentry>
    676                     <term>width</term>
    677 
    678                     <listitem>
    679                       <para>A positive fixnum</para>
    680                     </listitem>
    681                   </varlistentry>
    682                 </variablelist>
    683               </listitem>
    684             </varlistentry>
    685           </variablelist>
    686         </sect3>
    687 
    688         <sect3>
    689           <title>%int-to-ptr [Function]</title>
    690 
    691           <variablelist>
    692             <varlistentry>
    693               <term>Syntax</term>
    694 
    695               <listitem>
    696                 <para>%int-to-ptr int</para>
    697               </listitem>
    698             </varlistentry>
    699 
    700             <varlistentry>
    701               <term>Description</term>
    702 
    703               <listitem>
    704                 <para>Creates and returns a MACPTR whose address matches int.</para>
    705               </listitem>
    706             </varlistentry>
    707 
    708             <varlistentry>
    709               <term>Arguments</term>
    710 
    711               <listitem>
    712                 <para>&#x00A0;</para>
    713 
    714                 <variablelist>
    715                   <varlistentry>
    716                     <term>int</term>
    717 
    718                     <listitem>
    719                       <para>An (unsigned-byte 32)</para>
    720                     </listitem>
    721                   </varlistentry>
    722                 </variablelist>
    723               </listitem>
    724             </varlistentry>
    725           </variablelist>
    726         </sect3>
    727 
    728         <sect3>
    729           <title>%inc-ptr [Function]</title>
    730 
    731           <variablelist>
    732             <varlistentry>
    733               <term>Syntax</term>
    734 
    735               <listitem>
    736                 <para>%inc-ptr ptr &#38;optional (delta 1)</para>
    737               </listitem>
    738             </varlistentry>
    739 
    740             <varlistentry>
    741               <term>Description</term>
    742 
    743               <listitem>
    744                 <para>Creates and returns a MACPTR whose address is the address of
    745                 ptr plus delta. The idiom (%inc-ptr ptr 0) is sometimes used to
    746                 copy a MACPTR, e.g., to create a new MACPTR encapsulating the same
    747                 address as ptr.</para>
    748               </listitem>
    749             </varlistentry>
    750 
    751             <varlistentry>
    752               <term>Arguments</term>
    753 
    754               <listitem>
    755                 <para>&#x00A0;</para>
    756 
    757                 <variablelist>
    758                   <varlistentry>
    759                     <term>ptr</term>
    760 
    761                     <listitem>
    762                       <para>A MACPTR</para>
    763                     </listitem>
    764                   </varlistentry>
    765 
    766                   <varlistentry>
    767                     <term>delta</term>
    768 
    769                     <listitem>
    770                       <para>A fixnum</para>
    771                     </listitem>
    772                   </varlistentry>
    773                 </variablelist>
    774               </listitem>
    775             </varlistentry>
    776           </variablelist>
    777         </sect3>
    778 
    779         <sect3>
    780           <title>%ptr-to-int [Function]</title>
    781 
    782           <variablelist>
    783             <varlistentry>
    784               <term>Syntax</term>
    785 
    786               <listitem>
    787                 <para>%ptr-to-int ptr</para>
    788               </listitem>
    789             </varlistentry>
    790 
    791             <varlistentry>
    792               <term>Description</term>
    793 
    794               <listitem>
    795                 <para>Returns the address encapsulated by ptr, as an
    796                 (unsigned-byte 32).</para>
    797               </listitem>
    798             </varlistentry>
    799 
    800             <varlistentry>
    801               <term>Arguments</term>
    802 
    803               <listitem>
    804                 <para>&#x00A0;</para>
    805 
    806                 <variablelist>
    807                   <varlistentry>
    808                     <term>ptr</term>
    809 
    810                     <listitem>
    811                       <para>A MACPTR</para>
    812                     </listitem>
    813                   </varlistentry>
    814                 </variablelist>
    815               </listitem>
    816             </varlistentry>
    817           </variablelist>
    818         </sect3>
    819 
    820         <sect3>
    821           <title>%null-ptr [Macro]</title>
    822 
    823           <variablelist>
    824             <varlistentry>
    825               <term>Syntax</term>
    826 
    827               <listitem>
    828                 <para>%null-ptr</para>
    829               </listitem>
    830             </varlistentry>
    831 
    832             <varlistentry>
    833               <term>Description</term>
    834 
    835               <listitem>
    836                 <para>Equivalent to (%ptr-to-int 0).</para>
    837               </listitem>
    838             </varlistentry>
    839           </variablelist>
    840         </sect3>
    841 
    842         <sect3>
    843           <title>%null-ptr-p [Function]</title>
    844 
    845           <variablelist>
    846             <varlistentry>
    847               <term>Syntax</term>
    848 
    849               <listitem>
    850                 <para>%null-ptr-p ptr</para>
    851               </listitem>
    852             </varlistentry>
    853 
    854             <varlistentry>
    855               <term>Description</term>
    856 
    857               <listitem>
    858                 <para>Returns T If ptr is a MACPTR encapsulating the address 0,
    859                 NIL if ptr encapsulates some other address.</para>
    860               </listitem>
    861             </varlistentry>
    862 
    863             <varlistentry>
    864               <term>Arguments</term>
    865 
    866               <listitem>
    867                 <para>&#x00A0;</para>
    868 
    869                 <variablelist>
    870                   <varlistentry>
    871                     <term>ptr</term>
    872 
    873                     <listitem>
    874                       <para>A MACPTR</para>
    875                     </listitem>
    876                   </varlistentry>
    877                 </variablelist>
    878               </listitem>
    879             </varlistentry>
    880           </variablelist>
    881         </sect3>
    882 
    883         <sect3>
    884           <title>%setf-macptr [Function]</title>
    885 
    886           <variablelist>
    887             <varlistentry>
    888               <term>Syntax</term>
    889 
    890               <listitem>
    891                 <para>%setf-macptr dest-ptr src-ptr</para>
    892               </listitem>
    893             </varlistentry>
    894 
    895             <varlistentry>
    896               <term>Description</term>
    897 
    898               <listitem>
    899                 <para>Causes dest-ptr to encapsulate the same address that src-ptr
    900                 does, then returns dest-ptr.</para>
    901               </listitem>
    902             </varlistentry>
    903 
    904             <varlistentry>
    905               <term>Arguments</term>
    906 
    907               <listitem>
    908                 <para>&#x00A0;</para>
    909 
    910                 <variablelist>
    911                   <varlistentry>
    912                     <term>dest-ptr</term>
    913 
    914                     <listitem>
    915                       <para>A MACPTR</para>
    916                     </listitem>
    917                   </varlistentry>
    918 
    919                   <varlistentry>
    920                     <term>src-ptr</term>
    921 
    922                     <listitem>
    923                       <para>A MACPTR</para>
    924                     </listitem>
    925                   </varlistentry>
    926                 </variablelist>
    927               </listitem>
    928             </varlistentry>
    929           </variablelist>
    930         </sect3>
    931 
    932         <sect3>
    933           <title>%incf-ptr [Macro]</title>
    934 
    935           <variablelist>
    936             <varlistentry>
    937               <term>Syntax</term>
    938 
    939               <listitem>
    940                 <para>%incf-ptr ptr &#38;optional (delta 1)</para>
    941               </listitem>
    942             </varlistentry>
    943 
    944             <varlistentry>
    945               <term>Description</term>
    946 
    947               <listitem>
    948                 <para>Destructively modifies ptr, by adding delta to the address
    949                 it encapsulates. Returns ptr.</para>
    950               </listitem>
    951             </varlistentry>
    952 
    953             <varlistentry>
    954               <term>Arguments</term>
    955 
    956               <listitem>
    957                 <para>&#x00A0;</para>
    958 
    959                 <variablelist>
    960                   <varlistentry>
    961                     <term>ptr</term>
    962 
    963                     <listitem>
    964                       <para>A MACPTR</para>
    965                     </listitem>
    966                   </varlistentry>
    967 
    968                   <varlistentry>
    969                     <term>delta</term>
    970 
    971                     <listitem>
    972                       <para>A fixnum</para>
    973                     </listitem>
    974                   </varlistentry>
    975                 </variablelist>
    976               </listitem>
    977             </varlistentry>
    978           </variablelist>
    979         </sect3>
    980 
    981         <sect3>
    982           <title>with-macptrs [Macro]</title>
    983 
    984           <variablelist>
    985             <varlistentry>
    986               <term>Syntax</term>
    987 
    988               <listitem>
    989                 <para>with-macptrs (var expr)* &#38;body body</para>
    990               </listitem>
    991             </varlistentry>
    992 
    993             <varlistentry>
    994               <term>Description</term>
    995 
    996               <listitem>
    997                 <para>Executes body in an environment in which each var is bound
    998                 to a stack-allocated macptr which encapsulates the foreign address
    999                 yielded by the corresponding expr. Returns whatever value(s) body
    1000                 returns.</para>
    1001               </listitem>
    1002             </varlistentry>
    1003 
    1004             <varlistentry>
    1005               <term>Arguments</term>
    1006 
    1007               <listitem>
    1008                 <para>&#x00A0;</para>
    1009 
    1010                 <variablelist>
    1011                   <varlistentry>
    1012                     <term>var</term>
    1013 
    1014                     <listitem>
    1015                       <para>A symbol (variable name)</para>
    1016                     </listitem>
    1017                   </varlistentry>
    1018 
    1019                   <varlistentry>
    1020                     <term>expr</term>
    1021 
    1022                     <listitem>
    1023                       <para>A MACPTR-valued expression</para>
    1024                     </listitem>
    1025                   </varlistentry>
    1026                 </variablelist>
    1027               </listitem>
    1028             </varlistentry>
    1029           </variablelist>
    1030         </sect3>
    1031 
    1032         <sect3>
    1033           <title>%stack-block [Macro]</title>
    1034 
    1035           <variablelist>
    1036             <varlistentry>
    1037               <term>Syntax</term>
    1038 
    1039               <listitem>
    1040                 <para>%stack-block (var expr)* &#38;body body</para>
    1041               </listitem>
    1042             </varlistentry>
    1043 
    1044             <varlistentry>
    1045               <term>Description</term>
    1046 
    1047               <listitem>
    1048                 <para>Executes body in an environment in which each var is bound
    1049                 to a stack-allocated macptr which encapsulates the address of a
    1050                 stack-allocated region of size expr bytes. Returns whatever
    1051                 value(s) body returns.</para>
    1052               </listitem>
    1053             </varlistentry>
    1054 
    1055             <varlistentry>
    1056               <term>Arguments</term>
    1057 
    1058               <listitem>
    1059                 <para>&#x00A0;</para>
    1060 
    1061                 <variablelist>
    1062                   <varlistentry>
    1063                     <term>var</term>
    1064 
    1065                     <listitem>
    1066                       <para>A symbol (variable name)</para>
    1067                     </listitem>
    1068                   </varlistentry>
    1069 
    1070                   <varlistentry>
    1071                     <term>expr</term>
    1072 
    1073                     <listitem>
    1074                       <para>An expression which should evaluate to a non-negative
    1075                       fixnum</para>
    1076                     </listitem>
    1077                   </varlistentry>
    1078                 </variablelist>
    1079               </listitem>
    1080             </varlistentry>
    1081           </variablelist>
    1082         </sect3>
     668
     669                      <variablelist>
     670                        <varlistentry>
     671                          <term>bit-offset</term>
     672
     673                          <listitem>
     674                            <para>A fixnum</para>
     675                          </listitem>
     676                        </varlistentry>
     677
     678                        <varlistentry>
     679                          <term>width</term>
     680
     681                          <listitem>
     682                            <para>A positive fixnum</para>
     683                          </listitem>
     684                        </varlistentry>
     685                      </variablelist>
     686                </listitem>
     687              </varlistentry>
     688            </variablelist>
     689      </sect3>
     690
     691          <sect3>
     692            <title>%int-to-ptr [Function]</title>
     693
     694            <variablelist>
     695              <varlistentry>
     696                <term>Syntax</term>
     697
     698                <listitem>
     699                      <para>%int-to-ptr int</para>
     700                </listitem>
     701              </varlistentry>
     702
     703              <varlistentry>
     704                <term>Description</term>
     705
     706                <listitem>
     707                      <para>Creates and returns a MACPTR whose address matches int.</para>
     708                </listitem>
     709              </varlistentry>
     710
     711              <varlistentry>
     712                <term>Arguments</term>
     713
     714                <listitem>
     715                      <para>&#x00A0;</para>
     716
     717                      <variablelist>
     718                        <varlistentry>
     719                          <term>int</term>
     720
     721                          <listitem>
     722                            <para>An (unsigned-byte 32)</para>
     723                          </listitem>
     724                        </varlistentry>
     725                      </variablelist>
     726                </listitem>
     727              </varlistentry>
     728            </variablelist>
     729          </sect3>
     730
     731          <sect3>
     732            <title>%inc-ptr [Function]</title>
     733
     734            <variablelist>
     735              <varlistentry>
     736                <term>Syntax</term>
     737
     738                <listitem>
     739                      <para>%inc-ptr ptr &#38;optional (delta 1)</para>
     740                </listitem>
     741              </varlistentry>
     742
     743              <varlistentry>
     744                <term>Description</term>
     745
     746                <listitem>
     747                      <para>Creates and returns a MACPTR whose address is the address of
     748                        ptr plus delta. The idiom (%inc-ptr ptr 0) is sometimes used to
     749                        copy a MACPTR, e.g., to create a new MACPTR encapsulating the same
     750                        address as ptr.</para>
     751                </listitem>
     752              </varlistentry>
     753
     754              <varlistentry>
     755                <term>Arguments</term>
     756
     757                <listitem>
     758                      <para>&#x00A0;</para>
     759
     760                      <variablelist>
     761                        <varlistentry>
     762                          <term>ptr</term>
     763
     764                          <listitem>
     765                            <para>A MACPTR</para>
     766                          </listitem>
     767                        </varlistentry>
     768
     769                        <varlistentry>
     770                          <term>delta</term>
     771
     772                          <listitem>
     773                            <para>A fixnum</para>
     774                          </listitem>
     775                        </varlistentry>
     776                      </variablelist>
     777                </listitem>
     778              </varlistentry>
     779            </variablelist>
     780          </sect3>
     781
     782          <sect3>
     783            <title>%ptr-to-int [Function]</title>
     784
     785            <variablelist>
     786              <varlistentry>
     787                <term>Syntax</term>
     788
     789                <listitem>
     790                      <para>%ptr-to-int ptr</para>
     791                </listitem>
     792              </varlistentry>
     793
     794              <varlistentry>
     795                <term>Description</term>
     796
     797                <listitem>
     798                      <para>Returns the address encapsulated by ptr, as an
     799                        (unsigned-byte 32).</para>
     800                </listitem>
     801              </varlistentry>
     802
     803              <varlistentry>
     804                <term>Arguments</term>
     805
     806                <listitem>
     807                      <para>&#x00A0;</para>
     808
     809                      <variablelist>
     810                        <varlistentry>
     811                          <term>ptr</term>
     812
     813                          <listitem>
     814                            <para>A MACPTR</para>
     815                          </listitem>
     816                        </varlistentry>
     817                      </variablelist>
     818                </listitem>
     819              </varlistentry>
     820            </variablelist>
     821          </sect3>
     822
     823          <sect3>
     824            <title>%null-ptr [Macro]</title>
     825
     826            <variablelist>
     827              <varlistentry>
     828                <term>Syntax</term>
     829
     830                <listitem>
     831                      <para>%null-ptr</para>
     832                </listitem>
     833              </varlistentry>
     834
     835              <varlistentry>
     836                <term>Description</term>
     837
     838                <listitem>
     839                      <para>Equivalent to (%ptr-to-int 0).</para>
     840                </listitem>
     841              </varlistentry>
     842            </variablelist>
     843          </sect3>
     844
     845          <sect3>
     846            <title>%null-ptr-p [Function]</title>
     847
     848            <variablelist>
     849              <varlistentry>
     850                <term>Syntax</term>
     851
     852                <listitem>
     853                      <para>%null-ptr-p ptr</para>
     854                </listitem>
     855              </varlistentry>
     856
     857              <varlistentry>
     858                <term>Description</term>
     859
     860                <listitem>
     861                      <para>Returns T If ptr is a MACPTR encapsulating the address 0,
     862                        NIL if ptr encapsulates some other address.</para>
     863                </listitem>
     864              </varlistentry>
     865
     866              <varlistentry>
     867                <term>Arguments</term>
     868
     869                <listitem>
     870                      <para>&#x00A0;</para>
     871
     872                      <variablelist>
     873                        <varlistentry>
     874                          <term>ptr</term>
     875
     876                          <listitem>
     877                            <para>A MACPTR</para>
     878                          </listitem>
     879                        </varlistentry>
     880                      </variablelist>
     881                </listitem>
     882              </varlistentry>
     883            </variablelist>
     884          </sect3>
     885
     886          <sect3>
     887            <title>%setf-macptr [Function]</title>
     888
     889            <variablelist>
     890              <varlistentry>
     891                <term>Syntax</term>
     892
     893                <listitem>
     894                      <para>%setf-macptr dest-ptr src-ptr</para>
     895                </listitem>
     896              </varlistentry>
     897
     898              <varlistentry>
     899                <term>Description</term>
     900
     901                <listitem>
     902                      <para>Causes dest-ptr to encapsulate the same address that src-ptr
     903                        does, then returns dest-ptr.</para>
     904                </listitem>
     905              </varlistentry>
     906
     907              <varlistentry>
     908                <term>Arguments</term>
     909
     910                <listitem>
     911                      <para>&#x00A0;</para>
     912
     913                      <variablelist>
     914                        <varlistentry>
     915                          <term>dest-ptr</term>
     916
     917                          <listitem>
     918                            <para>A MACPTR</para>
     919                          </listitem>
     920                        </varlistentry>
     921
     922                        <varlistentry>
     923                          <term>src-ptr</term>
     924
     925                          <listitem>
     926                            <para>A MACPTR</para>
     927                          </listitem>
     928                        </varlistentry>
     929                      </variablelist>
     930                </listitem>
     931              </varlistentry>
     932            </variablelist>
     933          </sect3>
     934
     935          <sect3>
     936            <title>%incf-ptr [Macro]</title>
     937
     938            <variablelist>
     939              <varlistentry>
     940                <term>Syntax</term>
     941
     942                <listitem>
     943                      <para>%incf-ptr ptr &#38;optional (delta 1)</para>
     944                </listitem>
     945              </varlistentry>
     946
     947              <varlistentry>
     948                <term>Description</term>
     949
     950                <listitem>
     951                      <para>Destructively modifies ptr, by adding delta to the address
     952                        it encapsulates. Returns ptr.</para>
     953                </listitem>
     954              </varlistentry>
     955
     956              <varlistentry>
     957                <term>Arguments</term>
     958
     959                <listitem>
     960                      <para>&#x00A0;</para>
     961
     962                      <variablelist>
     963                        <varlistentry>
     964                          <term>ptr</term>
     965
     966                          <listitem>
     967                            <para>A MACPTR</para>
     968                          </listitem>
     969                        </varlistentry>
     970
     971                        <varlistentry>
     972                          <term>delta</term>
     973
     974                          <listitem>
     975                            <para>A fixnum</para>
     976                          </listitem>
     977                        </varlistentry>
     978                      </variablelist>
     979                </listitem>
     980              </varlistentry>
     981            </variablelist>
     982          </sect3>
     983
     984          <sect3>
     985            <title>with-macptrs [Macro]</title>
     986
     987            <variablelist>
     988              <varlistentry>
     989                <term>Syntax</term>
     990
     991                <listitem>
     992                      <para>with-macptrs (var expr)* &#38;body body</para>
     993                </listitem>
     994              </varlistentry>
     995
     996              <varlistentry>
     997                <term>Description</term>
     998
     999                <listitem>
     1000                      <para>Executes body in an environment in which each var is bound
     1001                        to a stack-allocated macptr which encapsulates the foreign address
     1002                        yielded by the corresponding expr. Returns whatever value(s) body
     1003                        returns.</para>
     1004                </listitem>
     1005              </varlistentry>
     1006
     1007              <varlistentry>
     1008                <term>Arguments</term>
     1009
     1010                <listitem>
     1011                      <para>&#x00A0;</para>
     1012
     1013                      <variablelist>
     1014                        <varlistentry>
     1015                          <term>var</term>
     1016
     1017                          <listitem>
     1018                            <para>A symbol (variable name)</para>
     1019                          </listitem>
     1020                        </varlistentry>
     1021
     1022                        <varlistentry>
     1023                          <term>expr</term>
     1024
     1025                          <listitem>
     1026                            <para>A MACPTR-valued expression</para>
     1027                          </listitem>
     1028                        </varlistentry>
     1029                      </variablelist>
     1030                </listitem>
     1031              </varlistentry>
     1032            </variablelist>
     1033          </sect3>
     1034
     1035          <sect3>
     1036            <title>%stack-block [Macro]</title>
     1037
     1038            <variablelist>
     1039              <varlistentry>
     1040                <term>Syntax</term>
     1041
     1042                <listitem>
     1043                      <para>%stack-block (var expr)* &#38;body body</para>
     1044                </listitem>
     1045              </varlistentry>
     1046
     1047              <varlistentry>
     1048                <term>Description</term>
     1049
     1050                <listitem>
     1051                      <para>Executes body in an environment in which each var is bound
     1052                        to a stack-allocated macptr which encapsulates the address of a
     1053                        stack-allocated region of size expr bytes. Returns whatever
     1054                        value(s) body returns.</para>
     1055                </listitem>
     1056              </varlistentry>
     1057
     1058              <varlistentry>
     1059                <term>Arguments</term>
     1060
     1061                <listitem>
     1062                      <para>&#x00A0;</para>
     1063
     1064                      <variablelist>
     1065                        <varlistentry>
     1066                          <term>var</term>
     1067
     1068                          <listitem>
     1069                            <para>A symbol (variable name)</para>
     1070                          </listitem>
     1071                        </varlistentry>
     1072
     1073                        <varlistentry>
     1074                          <term>expr</term>
     1075
     1076                          <listitem>
     1077                            <para>An expression which should evaluate to a non-negative
     1078                              fixnum</para>
     1079                          </listitem>
     1080                        </varlistentry>
     1081                      </variablelist>
     1082                </listitem>
     1083              </varlistentry>
     1084            </variablelist>
     1085          </sect3>
    10831086
    10841087          <sect3>
     
    10871090            <variablelist>
    10881091              <varlistentry>
    1089                 <term>Syntax</term>
    1090 
    1091                 <listitem>
    1092                   <para>make-cstring string</para>
    1093                 </listitem>
    1094               </varlistentry>
    1095 
    1096               <varlistentry>
    1097                 <term>Description</term>
    1098 
    1099                 <listitem>
    1100                   <para>Allocates a block of memory (via malloc) of length (1+
    1101                   (length string)). Copies the string to this block and appends a
    1102                   trailing NUL byte; returns a MACPTR to the block.</para>
    1103                 </listitem>
    1104               </varlistentry>
    1105 
    1106               <varlistentry>
    1107                 <term>Arguments</term>
    1108 
    1109                 <listitem>
    1110                   <para>&#x00A0;</para>
    1111 
    1112                   <variablelist>
    1113                     <varlistentry>
    1114                       <term>string</term>
    1115 
    1116                       <listitem>
    1117                         <para>A lisp string</para>
    1118                       </listitem>
    1119                     </varlistentry>
    1120                   </variablelist>
    1121                 </listitem>
     1092                    <term>Syntax</term>
     1093
     1094                    <listitem>
     1095                      <para>make-cstring string</para>
     1096                    </listitem>
     1097              </varlistentry>
     1098
     1099              <varlistentry>
     1100                    <term>Description</term>
     1101
     1102                    <listitem>
     1103                      <para>Allocates a block of memory (via malloc) of length (1+
     1104                        (length string)). Copies the string to this block and appends a
     1105                        trailing NUL byte; returns a MACPTR to the block.</para>
     1106                    </listitem>
     1107              </varlistentry>
     1108
     1109              <varlistentry>
     1110                    <term>Arguments</term>
     1111
     1112                    <listitem>
     1113                      <para>&#x00A0;</para>
     1114
     1115                      <variablelist>
     1116                        <varlistentry>
     1117                          <term>string</term>
     1118
     1119                          <listitem>
     1120                                <para>A lisp string</para>
     1121                          </listitem>
     1122                        </varlistentry>
     1123                      </variablelist>
     1124                    </listitem>
    11221125              </varlistentry>
    11231126            </variablelist>
    11241127          </sect3>
    11251128
    1126         <sect3>
    1127           <title>with-cstrs [Macro]</title>
    1128 
    1129           <variablelist>
    1130             <varlistentry>
    1131               <term>Syntax</term>
    1132 
    1133               <listitem>
    1134                 <para>with-cstrs (var string)* &#38;body body</para>
    1135               </listitem>
    1136             </varlistentry>
    1137 
    1138             <varlistentry>
    1139               <term>Description</term>
    1140 
    1141               <listitem>
    1142                 <para>Executes body in an environment in which each var is bound
    1143                 to a stack-allocated macptr which encapsulates the %address of a
    1144                 stack-allocated region of into which each string (and a trailing
    1145                 NUL byte) has been copied. Returns whatever value(s) body returns.</para>
    1146               </listitem>
    1147             </varlistentry>
    1148 
    1149             <varlistentry>
    1150               <term>Arguments</term>
    1151 
    1152               <listitem>
    1153                 <para>&#x00A0;</para>
    1154 
    1155                 <variablelist>
    1156                   <varlistentry>
    1157                     <term>var</term>
    1158 
    1159                     <listitem>
    1160                       <para>A symbol (variable name)</para>
    1161                     </listitem>
    1162                   </varlistentry>
    1163 
    1164                   <varlistentry>
    1165                     <term>string</term>
    1166 
    1167                     <listitem>
    1168                       <para>An expression which should evaluate to a lisp string</para>
    1169                     </listitem>
    1170                   </varlistentry>
    1171                 </variablelist>
    1172               </listitem>
    1173             </varlistentry>
    1174           </variablelist>
    1175         </sect3>
    1176 
    1177 <sect3>
    1178   <title>with-encoded-cstrs [Macro]</title>
    1179 
    1180   <variablelist>
    1181         <varlistentry>
    1182           <term>Syntax</term>
    1183 
    1184           <listitem>
    1185                 <para>with-encoded-cstrs ENCODING-NAME (varI stringI)* &#38;body body</para>
    1186           </listitem>
    1187         </varlistentry>
    1188 
    1189         <varlistentry>
    1190           <term>Description</term>
    1191 
    1192           <listitem>
    1193                 <para>Executes body in an environment in which each varI is
    1194                   bound to a macptr which encapsulates the %address of a
    1195                   stack-allocated region of into which each stringI (and a
    1196                   trailing NUL character) has been copied. Returns whatever
    1197                   value(s) body returns.</para>
    1198 
    1199         <para>ENCODING-NAME is a keyword constant that names a
    1200           character encoding. Each foreign string is encoded in the
    1201           named encoding. Each foreign string has dynamic
    1202           extent.</para>
    1203 
    1204         <para>WITH-ENCODED-CSTRS does not automatically prepend
    1205         bte-order marks to its output; the size of the terminating
    1206         #\NUL character depends on the number of octets per code unit
    1207         in the encoding.</para>
    1208 
    1209         <para>The expression</para>
    1210 
    1211         <programlisting>(ccl:with-cstrs ((x "x")) (#_puts x))</programlisting>
    1212 
    1213         <para>is functionally equivalent to</para>
    1214 
    1215         <programlisting>(ccl:with-encoded-cstrs :iso-8859-1 ((x "x")) (#_puts x))</programlisting>
    1216           </listitem>
    1217         </varlistentry>
    1218 
    1219         <varlistentry>
    1220           <term>Arguments</term>
    1221 
    1222           <listitem>
    1223                 <para>&#x00A0;</para>
    1224 
    1225                 <variablelist>
    1226                   <varlistentry>
    1227                     <term>varI</term>
    1228 
    1229                     <listitem>
    1230                       <para>A symbol (variable name)</para>
    1231                     </listitem>
    1232                   </varlistentry>
    1233 
    1234                   <varlistentry>
    1235                     <term>stringI</term>
    1236 
    1237                     <listitem>
    1238                       <para>An expression which should evaluate to a lisp string</para>
    1239                     </listitem>
    1240                   </varlistentry>
    1241                 </variablelist>
    1242           </listitem>
    1243         </varlistentry>
    1244   </variablelist>
    1245 </sect3>
    1246 
    1247         <sect3>
    1248           <title>%get-cstring [Function]</title>
    1249 
    1250           <variablelist>
    1251             <varlistentry>
    1252               <term>Syntax</term>
    1253 
    1254               <listitem>
    1255                 <para>%get-cstring ptr</para>
    1256               </listitem>
    1257             </varlistentry>
    1258 
    1259             <varlistentry>
    1260               <term>Description</term>
    1261 
    1262               <listitem>
    1263                 <para>Interprets ptr as a pointer to a (NUL -terminated) C string;
    1264                 returns an equivalent lisp string.</para>
    1265               </listitem>
    1266             </varlistentry>
    1267 
    1268             <varlistentry>
    1269               <term>Arguments</term>
    1270 
    1271               <listitem>
    1272                 <para></para>
    1273 
    1274                 <variablelist>
    1275                   <varlistentry>
    1276                     <term>ptr</term>
    1277 
    1278                     <listitem>
    1279                       <para>A MACPTR</para>
    1280                     </listitem>
    1281                   </varlistentry>
    1282                 </variablelist>
    1283               </listitem>
    1284             </varlistentry>
    1285           </variablelist>
    1286         </sect3>
    1287 
    1288         <sect3>
    1289           <title>%str-from-ptr [Function]</title>
    1290 
    1291           <variablelist>
    1292             <varlistentry>
    1293               <term>Syntax</term>
    1294 
    1295               <listitem>
    1296                 <para>%str-from-ptr ptr length</para>
    1297               </listitem>
    1298             </varlistentry>
    1299 
    1300             <varlistentry>
    1301               <term>Description</term>
    1302 
    1303               <listitem>
    1304                 <para>Returns a lisp string of length <varname>length</varname>,
    1305                 whose contents are initialized from the bytes at<varname> ptr.</varname>
    1306                 </para>
    1307               </listitem>
    1308             </varlistentry>
    1309 
    1310             <varlistentry>
    1311               <term>Arguments</term>
    1312 
    1313               <listitem>
    1314                 <para><variablelist><varlistentry><term>ptr</term><listitem><para>A
    1315                 MACPTR</para></listitem></varlistentry><varlistentry><term>length</term><listitem><para>a
    1316                 non-negative fixnum</para></listitem></varlistentry></variablelist></para>
    1317               </listitem>
    1318             </varlistentry>
    1319           </variablelist>
    1320         </sect3>
    1321       </sect2>
    1322     </sect1>
    1323 
    1324     <sect1 id="The-Interface-Database">
    1325       <title>The Interface Database</title>
    1326 
    1327       <sect2 id="interface-database-Overview">
    1328         <title>Overview</title>
    1329         <para>&CCL; uses a set of database files which contain
     1129          <sect3>
     1130            <title>with-cstrs [Macro]</title>
     1131
     1132            <variablelist>
     1133              <varlistentry>
     1134                <term>Syntax</term>
     1135
     1136                <listitem>
     1137                      <para>with-cstrs (var string)* &#38;body body</para>
     1138                </listitem>
     1139              </varlistentry>
     1140
     1141              <varlistentry>
     1142                <term>Description</term>
     1143
     1144                <listitem>
     1145                      <para>Executes body in an environment in which each var is bound
     1146                        to a stack-allocated macptr which encapsulates the %address of a
     1147                        stack-allocated region of into which each string (and a trailing
     1148                        NUL byte) has been copied. Returns whatever value(s) body returns.</para>
     1149                </listitem>
     1150              </varlistentry>
     1151
     1152              <varlistentry>
     1153                <term>Arguments</term>
     1154
     1155                <listitem>
     1156                      <para>&#x00A0;</para>
     1157
     1158                      <variablelist>
     1159                        <varlistentry>
     1160                          <term>var</term>
     1161
     1162                          <listitem>
     1163                            <para>A symbol (variable name)</para>
     1164                          </listitem>
     1165                        </varlistentry>
     1166
     1167                        <varlistentry>
     1168                          <term>string</term>
     1169
     1170                          <listitem>
     1171                            <para>An expression which should evaluate to a lisp string</para>
     1172                          </listitem>
     1173                        </varlistentry>
     1174                      </variablelist>
     1175                </listitem>
     1176              </varlistentry>
     1177            </variablelist>
     1178          </sect3>
     1179
     1180      <sect3>
     1181        <title>with-encoded-cstrs [Macro]</title>
     1182
     1183        <variablelist>
     1184              <varlistentry>
     1185                <term>Syntax</term>
     1186
     1187                <listitem>
     1188                      <para>with-encoded-cstrs ENCODING-NAME (varI stringI)* &#38;body body</para>
     1189                </listitem>
     1190              </varlistentry>
     1191
     1192              <varlistentry>
     1193                <term>Description</term>
     1194
     1195                <listitem>
     1196                      <para>Executes body in an environment in which each varI is
     1197                        bound to a macptr which encapsulates the %address of a
     1198                        stack-allocated region of into which each stringI (and a
     1199                        trailing NUL character) has been copied. Returns whatever
     1200                        value(s) body returns.</para>
     1201
     1202              <para>ENCODING-NAME is a keyword constant that names a
     1203                character encoding. Each foreign string is encoded in the
     1204                named encoding. Each foreign string has dynamic
     1205                extent.</para>
     1206
     1207              <para>WITH-ENCODED-CSTRS does not automatically prepend
     1208                bte-order marks to its output; the size of the terminating
     1209                #\NUL character depends on the number of octets per code unit
     1210                in the encoding.</para>
     1211
     1212              <para>The expression</para>
     1213
     1214              <programlisting>(ccl:with-cstrs ((x "x")) (#_puts x))</programlisting>
     1215
     1216              <para>is functionally equivalent to</para>
     1217
     1218              <programlisting>(ccl:with-encoded-cstrs :iso-8859-1 ((x "x")) (#_puts x))</programlisting>
     1219                </listitem>
     1220              </varlistentry>
     1221
     1222              <varlistentry>
     1223                <term>Arguments</term>
     1224
     1225                <listitem>
     1226                      <para>&#x00A0;</para>
     1227
     1228                      <variablelist>
     1229                        <varlistentry>
     1230                          <term>varI</term>
     1231
     1232                          <listitem>
     1233                            <para>A symbol (variable name)</para>
     1234                          </listitem>
     1235                        </varlistentry>
     1236
     1237                        <varlistentry>
     1238                          <term>stringI</term>
     1239
     1240                          <listitem>
     1241                            <para>An expression which should evaluate to a lisp string</para>
     1242                          </listitem>
     1243                        </varlistentry>
     1244                      </variablelist>
     1245                </listitem>
     1246              </varlistentry>
     1247        </variablelist>
     1248      </sect3>
     1249
     1250          <sect3>
     1251            <title>%get-cstring [Function]</title>
     1252
     1253            <variablelist>
     1254              <varlistentry>
     1255                <term>Syntax</term>
     1256
     1257                <listitem>
     1258                      <para>%get-cstring ptr</para>
     1259                </listitem>
     1260              </varlistentry>
     1261
     1262              <varlistentry>
     1263                <term>Description</term>
     1264
     1265                <listitem>
     1266                      <para>Interprets ptr as a pointer to a (NUL -terminated) C string;
     1267                        returns an equivalent lisp string.</para>
     1268                </listitem>
     1269              </varlistentry>
     1270
     1271              <varlistentry>
     1272                <term>Arguments</term>
     1273
     1274                <listitem>
     1275                      <para></para>
     1276
     1277                      <variablelist>
     1278                        <varlistentry>
     1279                          <term>ptr</term>
     1280
     1281                          <listitem>
     1282                            <para>A MACPTR</para>
     1283                          </listitem>
     1284                        </varlistentry>
     1285                      </variablelist>
     1286                </listitem>
     1287              </varlistentry>
     1288            </variablelist>
     1289          </sect3>
     1290
     1291          <sect3>
     1292            <title>%str-from-ptr [Function]</title>
     1293
     1294            <variablelist>
     1295              <varlistentry>
     1296                <term>Syntax</term>
     1297
     1298                <listitem>
     1299                      <para>%str-from-ptr ptr length</para>
     1300                </listitem>
     1301              </varlistentry>
     1302
     1303              <varlistentry>
     1304                <term>Description</term>
     1305
     1306                <listitem>
     1307                      <para>Returns a lisp string of length <varname>length</varname>,
     1308                        whose contents are initialized from the bytes at<varname> ptr.</varname>
     1309                      </para>
     1310                </listitem>
     1311              </varlistentry>
     1312
     1313              <varlistentry>
     1314                <term>Arguments</term>
     1315
     1316                <listitem>
     1317                      <para><variablelist><varlistentry><term>ptr</term><listitem><para>A
     1318                                MACPTR</para></listitem></varlistentry><varlistentry><term>length</term><listitem><para>a
     1319                                non-negative fixnum</para></listitem></varlistentry></variablelist></para>
     1320                </listitem>
     1321              </varlistentry>
     1322            </variablelist>
     1323          </sect3>
     1324    </sect2>
     1325  </sect1>
     1326
     1327  <!-- ******************************************  -->
     1328  <sect1 id="The-Interface-Database">
     1329    <title>The Interface Database</title>
     1330
     1331    <sect2 id="interface-database-Overview">
     1332          <title>Overview</title>
     1333      <para>&CCL; uses a set of database files which contain
    13301334        foreign type, record, constant, and function definitions
    13311335        derived from the operating system's header files, be that
     
    13341338        available; see the Distributions page for information about
    13351339        obtaining current interface database files.</para>
    1336         <para>Not surprisingly, different platforms use different database files.</para>
    1337         <para>&CCL; defines reader macros that consult these databases:</para>
    1338         <itemizedlist>
    1339           <listitem>
    1340             <para>#$foo looks up the value of the constant definition of foo</para>
    1341           </listitem>
    1342           <listitem>
    1343             <para>#_foo looks up the foreign function definition for foo</para>
    1344           </listitem>
     1340      <para>Not surprisingly, different platforms use different database files.</para>
     1341      <para>&CCL; defines reader macros that consult these databases:</para>
     1342          <itemizedlist>
     1343        <listitem>
     1344              <para>#$foo looks up the value of the constant definition of foo</para>
     1345            </listitem>
     1346            <listitem>
     1347              <para>#_foo looks up the foreign function definition for foo</para>
     1348            </listitem>
    13451349       
    1346         </itemizedlist>
    1347         <para>In both cases, the symbol foo is interned in the "OS"
     1350      </itemizedlist>
     1351      <para>In both cases, the symbol foo is interned in the "OS"
    13481352        package. The #$ reader macro has the side-effect of defining
    13491353        foo as a constant (as if via DEFCONSTANT); the #_ reader macro
    13501354        has the side effect of defining foo as a macro which will
    13511355        expand into an (EXTERNAL-CALL form.)</para>
    1352         <para>It's important to remember that the side-effect happens
     1356      <para>It's important to remember that the side-effect happens
    13531357        when the form containing the reader macro is
    13541358        read. Macroexpansion functions that expand into forms which
     
    13561360        might think that they do, unless the macros are expanded in
    13571361        the same lisp session as the reader macro was read in.</para>
    1358         <para>In addition, references to foreign type,
     1362      <para>In addition, references to foreign type,
    13591363        structure/union, and field names (when used in the RREF/PREF
    13601364        and RLET macros) will cause these database files to be
    13611365        consulted.</para>
    1362         <para>Since the &CCL; sources contain instances of these
     1366      <para>Since the &CCL; sources contain instances of these
    13631367        reader macros (and references to foreign record types and
    13641368        fields), compiling &CCL; from those sources depends on the
    13651369        ability to find and use (see <xref
    1366         linkend="Building-the-heap-image"/>).</para>
    1367       </sect2>
    1368 
    1369       <sect2 id="Other-issues">
    1370         <title>Other issues:</title>
    1371         <itemizedlist>
    1372           <listitem>
    1373             <para>&CCL; now preserves the case of external symbols
    1374             in itsdatabase files. See for information about case in
    1375             foreign symbol names.</para>
    1376           </listitem>
    1377           <listitem>
    1378             <para>The Linux databases are derived from a somewhat
    1379             arbitrary set of Linux header files. Linux is enough of a
    1380             moving target that it may be difficult to define a standard,
    1381             reference set of interfaces from which to derive a standard,
    1382             reference set of database files.This seems to be less of
    1383             an issue with Darwin and FreeBSD.</para>
    1384           </listitem>
    1385         </itemizedlist>
    1386         <para>For information about building the database files,
    1387         see <xref linkend="The-Interface-Translator"/>.</para>
    1388       </sect2>
    1389     </sect1>
    1390 
    1391     <sect1 id="Using-Interface-Directories">
    1392       <title>Using Interface Directories</title>
    1393 
    1394       <sect2 id="Interface-Directory-Overview">
    1395         <title>Overview</title>
    1396         <para>As distributed, the "ccl:headers;" (for LinuxPPC)
     1370                                        linkend="Building-the-heap-image"/>).</para>
     1371    </sect2>
     1372
     1373    <sect2 id="Other-issues">
     1374      <title>Other issues:</title>
     1375      <itemizedlist>
     1376        <listitem>
     1377              <para>&CCL; now preserves the case of external symbols
     1378                in itsdatabase files. See for information about case in
     1379                foreign symbol names.</para>
     1380            </listitem>
     1381            <listitem>
     1382              <para>The Linux databases are derived from a somewhat
     1383                arbitrary set of Linux header files. Linux is enough of a
     1384                moving target that it may be difficult to define a standard,
     1385                reference set of interfaces from which to derive a standard,
     1386                reference set of database files.This seems to be less of
     1387                an issue with Darwin and FreeBSD.</para>
     1388            </listitem>
     1389          </itemizedlist>
     1390      <para>For information about building the database files,
     1391            see <xref linkend="The-Interface-Translator"/>.</para>
     1392    </sect2>
     1393  </sect1>
     1394
     1395  <!-- ******************************************  -->
     1396  <sect1 id="Using-Interface-Directories">
     1397    <title>Using Interface Directories</title>
     1398
     1399    <sect2 id="Interface-Directory-Overview">
     1400          <title>Overview</title>
     1401      <para>As distributed, the "ccl:headers;" (for LinuxPPC)
    13971402        directory is organized like:</para>
    1398         <programlisting>
    1399 headers/
    1400 headers/gl/
    1401 headers/gl/C/
    1402 headers/gl/C/populate.sh
    1403 headers/gl/constants.cdb
    1404 headers/gl/functions.cdb
    1405 headers/gl/records.cdb
    1406 headers/gl/objc-classes.cdb
    1407 headers/gl/objc-methods.cdb
    1408 headers/gl/types.cdb
    1409 headers/gnome/
    1410 headers/gnome/C/
    1411 headers/gnome/C/populate.sh
    1412 headers/gnome/constants.cdb
    1413 headers/gnome/functions.cb
    1414 headers/gnome/records.cdb
    1415 headers/gnome/objc-classes.cdb
    1416 headers/gnome/objc-methods.cdb
    1417 headers/gnome/types.cdb
    1418 headers/gtk/
    1419 headers/gtk/C/
    1420 headers/gtk/C/populate.sh
    1421 headers/gtk/constants.cdb
    1422 headers/gtk/functions.cdb
    1423 headers/gtk/records.cdb
    1424 headers/gtk/objc-classes.cdb
    1425 headers/gtk/objc-methods.cdb
    1426 headers/gtk/types.cdb
    1427 headers/libc/
    1428 headers/libc/C/
    1429 headers/libc/C/populate.sh
    1430 headers/libc/constants.cdb
    1431 headers/libc/functions.cdb
    1432 headers/libc/records.cdb
    1433 headers/libc/objc-classes.cdb
    1434 headers/libc/objc-methods.cdb
    1435 headers/libc/types.cdb
    1436 </programlisting>
    1437         <para>e.g, as a set of parallel subdirectories, each with a
     1403      <programlisting>
     1404        headers/
     1405        headers/gl/
     1406        headers/gl/C/
     1407        headers/gl/C/populate.sh
     1408        headers/gl/constants.cdb
     1409        headers/gl/functions.cdb
     1410        headers/gl/records.cdb
     1411        headers/gl/objc-classes.cdb
     1412        headers/gl/objc-methods.cdb
     1413        headers/gl/types.cdb
     1414        headers/gnome/
     1415        headers/gnome/C/
     1416        headers/gnome/C/populate.sh
     1417        headers/gnome/constants.cdb
     1418        headers/gnome/functions.cb
     1419        headers/gnome/records.cdb
     1420        headers/gnome/objc-classes.cdb
     1421        headers/gnome/objc-methods.cdb
     1422        headers/gnome/types.cdb
     1423        headers/gtk/
     1424        headers/gtk/C/
     1425        headers/gtk/C/populate.sh
     1426        headers/gtk/constants.cdb
     1427        headers/gtk/functions.cdb
     1428        headers/gtk/records.cdb
     1429        headers/gtk/objc-classes.cdb
     1430        headers/gtk/objc-methods.cdb
     1431        headers/gtk/types.cdb
     1432        headers/libc/
     1433        headers/libc/C/
     1434        headers/libc/C/populate.sh
     1435        headers/libc/constants.cdb
     1436        headers/libc/functions.cdb
     1437        headers/libc/records.cdb
     1438        headers/libc/objc-classes.cdb
     1439        headers/libc/objc-methods.cdb
     1440        headers/libc/types.cdb
     1441      </programlisting>
     1442      <para>e.g, as a set of parallel subdirectories, each with a
    14381443        lowercase name and each of which contains a set of 6 database
    14391444        files and a "C" subdirectory which contains a shell script
    14401445        used in the database creation process.</para>
    1441         <para>As one might assume, the database files in each of these
     1446      <para>As one might assume, the database files in each of these
    14421447        subdirectories contain foreign type, constant, and function
    14431448        definitions - as well as Objective-C class and method info -that
     
    14491454        and "gnome" contain interface information from the GTK+1.2 and
    14501455        GNOME libraries, respectively.</para>
    1451         <para>For Darwin, the "ccl:darwin-headers" directory contains
     1456      <para>For Darwin, the "ccl:darwin-headers" directory contains
    14521457        a "libc" subdirectory, whose contents roughly correspond to
    14531458        those of "/usr/include" under Darwin, as well as
    14541459        subdirectories corresponding to the MacOSX Carbon and Cocoa
    14551460        frameworks.</para>
    1456         <para>To see the precise set of .h files used to generate the
     1461      <para>To see the precise set of .h files used to generate the
    14571462        database files in a given interface directory, consult the
    14581463        corresponding "populate.sh" shell script (in the interface
    14591464        directory's "C" subdirectory.)</para>
    1460         <para>The intent is that this initial set can be augmented to
     1465      <para>The intent is that this initial set can be augmented to
    14611466        meet local needs, and that this can be done in a fairly
    14621467        incremental fashion: one needn't have unrelated header files
    14631468        installed in order to generate interface databases for a
    14641469        package of interest.</para>
    1465         <para>Hopefully, this scheme will also make it easier to
     1470      <para>Hopefully, this scheme will also make it easier to
    14661471        distribute patches and bug fixes.</para>
    1467         <para>&CCL; maintains a list of directories; when looking
     1472      <para>&CCL; maintains a list of directories; when looking
    14681473        for a foreign type, constant, function, or record definition,
    14691474        it'll consult the database files in each directory on that
     
    14721477        look in other interface directories should it need to do
    14731478        so.</para>
    1474       </sect2>
    1475 
    1476       <sect2 id="Creating-new-interface-directories">
    1477         <title>Creating new interface directories</title>
    1478         <para>This example refers to "ccl:headers;", which is
     1479    </sect2>
     1480
     1481    <sect2 id="Creating-new-interface-directories">
     1482          <title>Creating new interface directories</title>
     1483      <para>This example refers to "ccl:headers;", which is
    14791484        appropriate for LinuxPPC. The procedure's analogous under
    14801485        Darwin, where the "ccl:darwin-headers;" directory would be
    14811486        used instead.</para>
    1482         <para>To create a new interface directory, "foo", and a set of
     1487      <para>To create a new interface directory, "foo", and a set of
    14831488        database files in that directory:</para>
    1484         <orderedlist continuation="restarts" inheritnum="ignore">
    1485           <listitem>
    1486             <para>Create a subdirectory of &#34;ccl:headers;&#34; named
    1487             &#34;foo&#34;.</para>
    1488           </listitem>
    1489 
    1490           <listitem>
    1491             <para>Create a subdirectory of &#34;ccl:headers;foo;&#34; named
    1492             &#34;C&#34;.</para>
    1493           </listitem>
    1494 
    1495           <listitem>
    1496             <para>Create a file in &#34;ccl:headers;foo;C;&#34; named
    1497             &#34;populate.sh&#34;.</para>
    1498 
    1499             <para>One way of accomplishing the above steps is:</para>
    1500 
    1501             <programlisting format="linespecific">? (close (open &#34;ccl:headers;foo;C;populate.sh&#34; :direction :output :
    1502                if-does-not-exist :create :if-exists :overwrite))</programlisting>
    1503           </listitem>
    1504 
    1505           <listitem>
    1506             <para>Edit the file created above, using the &#34;populate.sh&#34;
    1507             files in the distribution as guidelines.</para>
    1508 
    1509             <para>The file might wind up looking something like:</para>
    1510 
    1511             <programlisting format="linespecific">#/bin/sh
    1512 h-to-ffi.sh `foo-config -cflags` /usr/include/foo/foo.h</programlisting>
    1513           </listitem>
    1514         </orderedlist>
    1515 
    1516         <para>Refer to <xref linkend="The-Interface-Translator"/> for
     1489          <orderedlist continuation="restarts" inheritnum="ignore">
     1490            <listitem>
     1491              <para>Create a subdirectory of &#34;ccl:headers;&#34; named
     1492                &#34;foo&#34;.</para>
     1493            </listitem>
     1494
     1495            <listitem>
     1496              <para>Create a subdirectory of &#34;ccl:headers;foo;&#34; named
     1497                &#34;C&#34;.</para>
     1498            </listitem>
     1499
     1500            <listitem>
     1501              <para>Create a file in &#34;ccl:headers;foo;C;&#34; named
     1502                &#34;populate.sh&#34;.</para>
     1503
     1504              <para>One way of accomplishing the above steps is:</para>
     1505
     1506              <programlisting format="linespecific">
     1507            ? (close (open &#34;ccl:headers;foo;C;populate.sh&#34; :direction :output :
     1508                           if-does-not-exist :create :if-exists :overwrite))
     1509          </programlisting>
     1510            </listitem>
     1511
     1512            <listitem>
     1513              <para>Edit the file created above, using the &#34;populate.sh&#34;
     1514                files in the distribution as guidelines.</para>
     1515
     1516              <para>The file might wind up looking something like:</para>
     1517
     1518              <programlisting format="linespecific">#/bin/sh
     1519            h-to-ffi.sh `foo-config -cflags` /usr/include/foo/foo.h</programlisting>
     1520            </listitem>
     1521          </orderedlist>
     1522
     1523      <para>Refer to <xref linkend="The-Interface-Translator"/> for
    15171524        information about running the interface translator and .ffi
    15181525        parser.</para>
    1519         <para>Assuming that all went well, there should now be .cdb
     1526      <para>Assuming that all went well, there should now be .cdb
    15201527        files in "ccl:headers;foo;". You can then do
    15211528        <programlisting>
    1522 ? (use-interface-dir :foo)
    1523         </programlisting>
    1524         whenever you need to
     1529          ? (use-interface-dir :foo)
     1530            </programlisting>
     1531            whenever you need to
    15251532        access the foreign type information in those database
    15261533        files.</para>
    1527       </sect2>
    1528     </sect1>
    1529 
    1530     <sect1 id="Using-Shared-Libraries">
    1531       <title>Using Shared Libraries</title>
    1532 
    1533       <sect2 id="Shared-Library-Overview">
    1534         <title>Overview</title>
    1535 
    1536         <para>&CCL; provides facilities to open and close shared
     1534    </sect2>
     1535  </sect1>
     1536
     1537  <!-- ******************************************  -->
     1538  <sect1 id="Using-Shared-Libraries">
     1539    <title>Using Shared Libraries</title>
     1540
     1541    <sect2 id="Shared-Library-Overview">
     1542          <title>Overview</title>
     1543
     1544      <para>&CCL; provides facilities to open and close shared
    15371545        libraries.</para>
    1538         <para>"Opening" a shared library, which is done with <xref
    1539         linkend="f_open-shared-library"/>, maps the library's code and
     1546      <para>"Opening" a shared library, which is done with <xref
     1547                                                              linkend="f_open-shared-library"/>, maps the library's code and
    15401548        data into &CCL;'s address space and makes its exported
    15411549        symbols accessible to &CCL;.</para>
    1542         <para>"Closing" a shared library, which is done with <xref
    1543         linkend="f_close-shared-library"/>, unmaps the library's code
     1550      <para>"Closing" a shared library, which is done with <xref
     1551                                                              linkend="f_close-shared-library"/>, unmaps the library's code
    15441552        and and removes the library's symbols from the global
    15451553        namespace.</para>
    1546         <para>A small number of shared libraries (including libc,
     1554      <para>A small number of shared libraries (including libc,
    15471555        libm, libdl under Linux, and the "system" library under
    15481556        Darwin) are opened by the lisp kernel and can't be
    15491557        closed.</para>
    1550         <para>&CCL; uses data structures of type
     1558      <para>&CCL; uses data structures of type
    15511559        EXTERNAL-ENTRY-POINT to map a foreign function name (string)
    15521560        to that foreign function's <emphasis>current</emphasis>
     
    15551563        different addresses; it may vary within a session for similar
    15561564        reasons.)</para>
    1557         <para>An EXTERNAL-ENTRY-POINT whose address is known is said
     1565      <para>An EXTERNAL-ENTRY-POINT whose address is known is said
    15581566        to be <emphasis>resolved</emphasis>. When an external entry
    15591567        point is resolved, the shared library which defines that entry
     
    15651573        entrypoint that was defined in a closed library will cause an
    15661574        attempt to reopen that library.</para>
    1567         <para>&CCL; keeps track of all libraries that have been
     1575      <para>&CCL; keeps track of all libraries that have been
    15681576        opened in a lisp session. When a saved application is first
    15691577        started, an attempt is made to reopen all libraries that were
     
    15721580        image was saved. Either of these attempts can fail "quietly",
    15731581        leaving some entry points in an unresolved state.</para>
    1574         <para>Linux shared libraries can be referred to either by a
     1582      <para>Linux shared libraries can be referred to either by a
    15751583        string which describes their full pathname or by their
    15761584        <emphasis>soname</emphasis>, a shorter string that can be
     
    15801588        several names; the library's soname is often the most
    15811589        appropriate identifier.</para>
    1582         <para>sonames are often less version-specific than other names
     1590      <para>sonames are often less version-specific than other names
    15831591        for libraries; a program that refers to a library by the name
    15841592        "libc.so.6" is more portable than one which refers to
     
    15861594        two names might each be platform-specific aliases of the
    15871595        first.</para>
    1588         <para>All of the global symbols described below are exported
     1596      <para>All of the global symbols described below are exported
    15891597        from the CCL package.</para>
    1590       </sect2>
    1591 
    1592       <sect2 id="Limitations-and-known-bugs--1-">
    1593         <title>Limitations and known bugs</title>
    1594         <itemizedlist>
    1595           <listitem>
    1596             <para>Don't get me started.</para>
    1597           </listitem>
    1598           <listitem>
    1599             <para>The underlying functionality has a poor notion of
    1600             dependency;it's not always possible to open libraries that
    1601             depend on unopened libraries, but it's possible to close
    1602             libraries on which other libraries depend. It
    1603             <emphasis>may</emphasis> be possible to generate
    1604             more explicit dependency information by parsing the output
    1605             of the Linux ldd and ldconfig programs.</para>
    1606           </listitem>
     1598    </sect2>
     1599
     1600    <sect2 id="Limitations-and-known-bugs--1-">
     1601      <title>Limitations and known bugs</title>
     1602          <itemizedlist>
     1603        <listitem>
     1604              <para>Don't get me started.</para>
     1605            </listitem>
     1606        <listitem>
     1607              <para>The underlying functionality has a poor notion of
     1608                dependency;it's not always possible to open libraries that
     1609                depend on unopened libraries, but it's possible to close
     1610                libraries on which other libraries depend. It
     1611                <emphasis>may</emphasis> be possible to generate
     1612                more explicit dependency information by parsing the output
     1613                of the Linux ldd and ldconfig programs.</para>
     1614            </listitem>
    16071615       
    1608         </itemizedlist>
    1609       </sect2>
    1610 
    1611       <sect2 id="Darwin-Notes">
    1612         <title>>Darwin Notes</title>
    1613         <para>Darwin shared libraries come in two (basic) flavors:</para>
    1614         <itemizedlist>
    1615           <listitem>
    1616             <para>"dylibs" (which often have the extension".dylib")
    1617             are primarily intended to be linked against atcompile/link
    1618             time. They can be loaded dynamically,<emphasis>but can't
    1619             be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
    1620             can be used to open a .dylib-style library;calling
    1621             CLOSE-SHARED-LIBRARY on the result of such a callproduces
    1622             a warning, and has no other effect.It appears that (due to
    1623             an OS bug) attempts to open .dylibshared-libraries that
    1624             are already open can cause memory corruptionunless the
    1625             full pathname of the .dylib file is specified on thefirst
    1626             and all subsequent calls.</para>
    1627           </listitem>
    1628           <listitem>
    1629             <para>"bundles" are intended to serve as application
    1630             extensions; they can be opened multiple times (creating
    1631             multiple instances of the library!) and closed
    1632             properly.</para>
    1633           </listitem>
    1634         </itemizedlist>
    1635         <para>Thanks to Michael Klingbeil for getting both kinds of
     1616          </itemizedlist>
     1617    </sect2>
     1618
     1619    <sect2 id="Darwin-Notes">
     1620      <title>>Darwin Notes</title>
     1621          <para>Darwin shared libraries come in two (basic) flavors:</para>
     1622          <itemizedlist>
     1623        <listitem>
     1624              <para>"dylibs" (which often have the extension".dylib")
     1625                are primarily intended to be linked against atcompile/link
     1626                time. They can be loaded dynamically,<emphasis>but can't
     1627                  be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
     1628                can be used to open a .dylib-style library;calling
     1629                CLOSE-SHARED-LIBRARY on the result of such a callproduces
     1630                a warning, and has no other effect.It appears that (due to
     1631                an OS bug) attempts to open .dylibshared-libraries that
     1632                are already open can cause memory corruptionunless the
     1633                full pathname of the .dylib file is specified on thefirst
     1634                and all subsequent calls.</para>
     1635            </listitem>
     1636        <listitem>
     1637              <para>"bundles" are intended to serve as application
     1638                extensions; they can be opened multiple times (creating
     1639                multiple instances of the library!) and closed
     1640                properly.</para>
     1641        </listitem>
     1642          </itemizedlist>
     1643      <para>Thanks to Michael Klingbeil for getting both kinds of
    16361644        Darwin shared libraries working in &CCL;.</para>
    1637       </sect2>
    1638     </sect1>
    1639 
    1640     <sect1 id="The-Interface-Translator">
    1641       <title>The Interface Translator</title>
    1642 
    1643       <sect2 id="Inteface-translator-overview">
    1644         <title>Overview</title>
    1645         <para>&CCL; uses an interface translation system based on the FFIGEN
    1646         system, which is described at
    1647         http://www.ccs.neu.edu/home/lth/ffigen/.
    1648         The interface translator makes
    1649         the constant, type, structure, and function definitions in a set of
    1650         C-language header files available to lisp code.</para>
    1651         <para>The basic idea of the FFIGEN scheme is to use the C
     1645    </sect2>
     1646  </sect1>
     1647
     1648  <!-- ******************************************  -->
     1649  <sect1 id="The-Interface-Translator">
     1650    <title>The Interface Translator</title>
     1651
     1652    <sect2 id="Inteface-translator-overview">
     1653          <title>Overview</title>
     1654          <para>&CCL; uses an interface translation system based on the FFIGEN
     1655            system, which is described at
     1656            http://www.ccs.neu.edu/home/lth/ffigen/.
     1657            The interface translator makes
     1658            the constant, type, structure, and function definitions in a set of
     1659            C-language header files available to lisp code.</para>
     1660      <para>The basic idea of the FFIGEN scheme is to use the C
    16521661        compiler's frontend and parser to translate .h files into
    16531662        semantically equivalent .ffi files, which represent the
     
    16571666        semantics of header file inclusion or the arcana of C
    16581667        parsing.</para>
    1659         <para>The original FFIGEN system used a modified version of
     1668      <para>The original FFIGEN system used a modified version of
    16601669        the LCC C compiler to produce .ffi files. Since many LinuxPPC
    16611670        header files contain GCC-specific constructs, &CCL;'s
    16621671        translation system uses a modified version of GCC (called,
    16631672        somewhat confusingly, ffigen.)</para>
    1664         <para>A version of ffigen based on GCC-4.0 was developed
     1673      <para>A version of ffigen based on GCC-4.0 was developed
    16651674        during the spring and summer of 2005.  Sources (diffs relative
    16661675        to the GCC-4.0 release) are available here, and binaries are
     
    16681677        should be insensitive to to the version of GCC (and its
    16691678        preprocessor) installed on the system.</para>
    1670         <para>An older version was developed in 2001-2002; it depended
     1679      <para>An older version was developed in 2001-2002; it depended
    16711680        on the installed version of GCC being 2.95.  It may still be
    16721681        of interest for people unable to run the GCC-4.0-based version
    16731682        for whatever reason.</para>
    1674         <para>A LinuxPPC binary of this older version is available at
     1683      <para>A LinuxPPC binary of this older version is available at
    16751684        ftp://clozure.com/pub/ffigen-0.1.tar.gz, and LinuxPPC source
    16761685        differences are at
    16771686        ftp://clozure.com/pub/ffigen-src.tar.gz.</para>
    1678         <para>For Darwin, the binary of the older FFIGEN is available
     1687      <para>For Darwin, the binary of the older FFIGEN is available
    16791688        at ftp://clozure.com/pub/ffigen-darwin.tar.gz, and the source
    16801689        differences are at
    16811690        ftp://clozure.com/pub/ffigen-darwin-src.tar.gz.</para>
    1682         <para>A shell script (distributed with the source and binary
     1691      <para>A shell script (distributed with the source and binary
    16831692        packages) called h-to-ffi.sh reads a specified .h file (and
    16841693        optional preprocessor arguments) and writes a (hopefully)
     
    16861695        C preprocessor and the ffigen program with appropriate
    16871696        arguments.</para>
    1688         <para>For each interface directory (see FIXTHIS)
     1697      <para>For each interface directory (see FIXTHIS)
    16891698        <emphasis>subdir</emphasis> distributed with &CCL;, a shell
    16901699        script (distributed with &CCL; as
     
    16931702        for Darwin)) calls h-to-ffi.sh on a large number of the header
    16941703        files in /usr/include (or some other <emphasis>system header
    1695         path</emphasis>) and creates a parallel directory tree in
     1704          path</emphasis>) and creates a parallel directory tree in
    16961705        "ccl:headers;<emphasis>subdir</emphasis>;C;<emphasis>system</emphasis>;<emphasis>header</emphasis>;<emphasis>path</emphasis>;"
    16971706        (or
    16981707        "ccl:darwin-headers;<emphasis>subdir</emphasis>;C;<emphasis>system</emphasis>;<emphasis>header</emphasis>;<emphasis>path</emphasis>;"),
    16991708        populating that directory with .ffi files.</para>
    1700         <para>A lisp function defined in "ccl:library;parse-ffi.lisp"
     1709      <para>A lisp function defined in "ccl:library;parse-ffi.lisp"
    17011710        reads the .ffi files in a specified interface directory
    17021711        <emphasis>subdir</emphasis> and generates new versions of the
    17031712        databases (files with the extension .cdb).</para>
    1704         <para>The CDB databases are used by the #$ and #_ reader
     1713      <para>The CDB databases are used by the #$ and #_ reader
    17051714        macros and are used in the expansion of RREF, RLET, and
    17061715        related macros.</para>
    1707       </sect2>
    1708 
    1709       <sect2 id="Details--rebuilding-the-CDB-databases--step-by-step">
    1710         <title>Details: rebuilding the CDB databases, step by step</title>
    1711         <orderedlist>
    1712           <listitem>
    1713             <para>Ensure that the FFIGEN program is installed. See
    1714             the"README" file in the source or binary archive for
    1715             specificinstallation instructions.This example assumes
    1716             LinuxPPC; for 32-bit DarwinPPC,
    1717             substitute"ccl:darwin-headers;" for "ccl:headers;".  For
    1718             64-bit DarwinPPC,substitute
    1719             "ccl:darwin-headers64;".</para>
    1720           </listitem>
    1721           <listitem>
    1722             <para>Edit the
    1723             "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"shell
    1724             script. When you're confident that the files
    1725             andpreprocessor options match your environment, cd to
    1726             the"ccl:headers;<emphasis>subdir</emphasis>;C;" directory
    1727             andinvoke ./populate.sh. Repeat this step until you're
    1728             able tocleanly translate all files refrenced in the shell
    1729             script.</para>
    1730           </listitem>
    1731           <listitem>
    1732             <para>Run &CCL;:
     1716    </sect2>
     1717
     1718    <sect2 id="Details--rebuilding-the-CDB-databases--step-by-step">
     1719      <title>Details: rebuilding the CDB databases, step by step</title>
     1720          <orderedlist>
     1721            <listitem>
     1722              <para>Ensure that the FFIGEN program is installed. See
     1723                the"README" file in the source or binary archive for
     1724                specificinstallation instructions.This example assumes
     1725                LinuxPPC; for 32-bit DarwinPPC,
     1726                substitute"ccl:darwin-headers;" for "ccl:headers;".  For
     1727                64-bit DarwinPPC,substitute
     1728                "ccl:darwin-headers64;".</para>
     1729            </listitem>
     1730        <listitem>
     1731              <para>Edit the
     1732                "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"shell
     1733                script. When you're confident that the files
     1734                andpreprocessor options match your environment, cd to
     1735                the"ccl:headers;<emphasis>subdir</emphasis>;C;" directory
     1736                andinvoke ./populate.sh. Repeat this step until you're
     1737                able tocleanly translate all files refrenced in the shell
     1738                script.</para>
     1739            </listitem>
     1740            <listitem>
     1741              <para>Run &CCL;:
    17331742            <programlisting>
    1734 ? (require "PARSE-FFI")
    1735 PARSE-FFI
    1736 
    1737 ? (parse-standard-ffi-files :SUBDIR)
    1738 ;;; lots of output ... after a while, shiny new .cdb files should
    1739 ;;; appear in "ccl:headers;subdir;"
    1740 ;;; (or "ccl:darwin-headers;subdir;" under Darwin)
    1741 </programlisting></para>
    1742           </listitem>
    1743         </orderedlist>
    1744       </sect2>
    1745     </sect1>
    1746 
    1747     <sect1 id="Case-sensitivity-of-foreign-names-in-CCL">
    1748       <title>Case-sensitivity of foreign names in &CCL;</title>
    1749 
    1750       <sect2 id="Case-sensitivity-overview">
    1751         <title>Overview</title>
    1752         <para>As of release 0.11, &CCL; addresses the fact that
    1753         foreign type, constant, record, field, and function nams are
    1754         case-sensitive and provides mechanisms to refer to these names
    1755         via lisp symbols.</para>
    1756         <para>Previous versions of &CCL; have tried to ignore that
     1743              ? (require "PARSE-FFI")
     1744              PARSE-FFI
     1745
     1746              ? (parse-standard-ffi-files :SUBDIR)
     1747              ;;; lots of output ... after a while, shiny new .cdb files should
     1748              ;;; appear in "ccl:headers;subdir;"
     1749              ;;; (or "ccl:darwin-headers;subdir;" under Darwin)
     1750          </programlisting></para>
     1751            </listitem>
     1752          </orderedlist>
     1753    </sect2>
     1754  </sect1>
     1755
     1756  <!-- ******************************************  -->
     1757  <sect1 id="Case-sensitivity-of-foreign-names-in-CCL">
     1758    <title>Case-sensitivity of foreign names in &CCL;</title>
     1759
     1760    <sect2 id="Case-sensitivity-overview">
     1761          <title>Overview</title>
     1762          <para>As of release 0.11, &CCL; addresses the fact that
     1763            foreign type, constant, record, field, and function nams are
     1764            case-sensitive and provides mechanisms to refer to these names
     1765            via lisp symbols.</para>
     1766      <para>Previous versions of &CCL; have tried to ignore that
    17571767        fact, under the belief that case conflicts were rare and that
    17581768        many users (and implementors) would prefer not to deal with
     
    17641774        than other approaches that I'd thought of. I'd be interested
    17651775        to hear alternate proposals.</para>
    1766         <para>The issues described here have to do with how lisp
     1776      <para>The issues described here have to do with how lisp
    17671777        symbols are used to denote foreign functions, constants,
    17681778        types, records, and fields. It doesn't affect how other lisp
     
    17701780        instance, the first argument to the EXTERNAL-CALL macros is
    17711781        now and has always been a case-sensitive string.</para>
    1772       </sect2>
    1773 
    1774       <sect2 id="Foreign-constant-and-function-names">
    1775         <title>Foreign constant and function names</title>
    1776         <para>The primary way of referring to foreign constant and
     1782    </sect2>
     1783
     1784    <sect2 id="Foreign-constant-and-function-names">
     1785          <title>Foreign constant and function names</title>
     1786      <para>The primary way of referring to foreign constant and
    17771787        function names in &CCL; is via the #$ and #_ reader
    17781788        macros. These reader macro functions each read a symbol into
     
    17811791        constant to the symbol or install a macroexpansion function on
    17821792        the symbol.</para>
    1783         <para>In order to observe case-sensitivity, the reader-macros
     1793      <para>In order to observe case-sensitivity, the reader-macros
    17841794        now read the symbol with (READTABLE-CASE :PRESERVE) in
    17851795        effect.</para>
    1786         <para>This means that it's necessary to type the foreign
     1796      <para>This means that it's necessary to type the foreign
    17871797        constant or function name in correct case, but it isn't
    17881798        necessary to use any special escaping constructs when writing
    17891799        the variable name. For instance:</para>
    1790         <programlisting>
    1791 (#_read fd buf n) ; refers to foreign symbol "read"
    1792 (#_READ fd buf n) ; refers to foreign symbol "READ", which may
    1793 ; not exist ...
    1794 #$o_rdonly ; Probably doesn't exist
    1795 #$O_RDONLY ; Exists on most platforms
    1796 </programlisting>
    1797       </sect2>
    1798 
    1799       <sect2 id="Foreign-type--record--and-field-names">
    1800         <title>Foreign type, record, and field names</title>
    1801         <para>Constructs like RLET expect a foreign type or record
    1802         name to be denoted by a symbol (typically a keyword); RREF
    1803         (and PREF) expect an "accessor" form, typically a keyword
    1804         formed by concatenating a foreign type or record name with a
    1805         sequence of one or more foreign field names, separated by
    1806         dots. These names are interned by the reader as other lisp
    1807         symbols are, with an arbitrary value of READTABLE-CASE in
    1808         effect (typically :UPCASE.) It seems like it would be very
    1809         tedious to force users to manually escape (via vertical bar or
    1810         backslash syntax) all lowercase characters in symbols used to
    1811         specify foreign type, record, and field names (especially
    1812         given that many traditional POSIX structure, type, and field
    1813         names are entirely lowercase.)</para>
    1814         <para>The approach taken by &CCL; is to allow the symbols
     1800      <programlisting>
     1801        (#_read fd buf n) ; refers to foreign symbol "read"
     1802        (#_READ fd buf n) ; refers to foreign symbol "READ", which may
     1803        ; not exist ...
     1804        #$o_rdonly ; Probably doesn't exist
     1805        #$O_RDONLY ; Exists on most platforms
     1806      </programlisting>
     1807    </sect2>
     1808
     1809    <sect2 id="Foreign-type--record--and-field-names">
     1810          <title>Foreign type, record, and field names</title>
     1811          <para>Constructs like RLET expect a foreign type or record
     1812            name to be denoted by a symbol (typically a keyword); RREF
     1813            (and PREF) expect an "accessor" form, typically a keyword
     1814            formed by concatenating a foreign type or record name with a
     1815            sequence of one or more foreign field names, separated by
     1816            dots. These names are interned by the reader as other lisp
     1817            symbols are, with an arbitrary value of READTABLE-CASE in
     1818            effect (typically :UPCASE.) It seems like it would be very
     1819            tedious to force users to manually escape (via vertical bar or
     1820            backslash syntax) all lowercase characters in symbols used to
     1821            specify foreign type, record, and field names (especially
     1822            given that many traditional POSIX structure, type, and field
     1823            names are entirely lowercase.)</para>
     1824      <para>The approach taken by &CCL; is to allow the symbols
    18151825        (keywords) used to denote foreign type, record, and field
    18161826        names to contain angle brackets (<literal>&lt;</literal> and
    18171827        <literal>&gt;</literal>). Such symbols are translated to
    1818         foreign names via the following set of conventions:</para>
    1819         <itemizedlist>
    1820           <listitem>
    1821             <para>All instances of &lt; and &gt; in the symbol's pname
    1822             are balanced and don't nest.</para>
    1823           </listitem>
    1824           <listitem>
    1825             <para>Any alphabetic characters in the symbol's pname
    1826             thataren't enclosed in angle brackets are treated as
    1827             lower-case,regardless of the value of READTABLE-CASE and
    1828             regardless of the case in which they were written.</para>
    1829           </listitem>
    1830           <listitem>
    1831             <para>Alphabetic characters that appear within angle
    1832             brackets aremapped to upper-case, again regardless of how
    1833             they were written orinterned.</para>
    1834           </listitem>
    1835         </itemizedlist>
    1836         <para>There may be many ways of "escaping" (with angle
    1837         brackets) sequences of upper-case and non-lower-case
    1838         characters in a symbol used to denote a foreign name. When
    1839         translating in the other direction, &CCL; always escapes the
    1840         longest sequence that starts with an upper-case character and
    1841         doesn't contain a lower-case character.</para>
    1842         <para>It's often preferable to use this canonical form of a
     1828            foreign names via the following set of conventions:</para>
     1829          <itemizedlist>
     1830        <listitem>
     1831              <para>All instances of &lt; and &gt; in the symbol's pname
     1832                are balanced and don't nest.</para>
     1833            </listitem>
     1834        <listitem>
     1835              <para>Any alphabetic characters in the symbol's pname
     1836                thataren't enclosed in angle brackets are treated as
     1837                lower-case,regardless of the value of READTABLE-CASE and
     1838                regardless of the case in which they were written.</para>
     1839            </listitem>
     1840        <listitem>
     1841              <para>Alphabetic characters that appear within angle
     1842                brackets aremapped to upper-case, again regardless of how
     1843                they were written orinterned.</para>
     1844            </listitem>
     1845      </itemizedlist>
     1846          <para>There may be many ways of "escaping" (with angle
     1847            brackets) sequences of upper-case and non-lower-case
     1848            characters in a symbol used to denote a foreign name. When
     1849            translating in the other direction, &CCL; always escapes the
     1850            longest sequence that starts with an upper-case character and
     1851            doesn't contain a lower-case character.</para>
     1852      <para>It's often preferable to use this canonical form of a
    18431853        foreign type name.</para>
    1844         <para>The accessor forms used by PREF/RREF should be viewed as
     1854      <para>The accessor forms used by PREF/RREF should be viewed as
    18451855        a series of foreign type/record and field names; upper-case
    18461856        sequences in the component names should be escaped with angle
     
    18481858        simply, the separating dots shouldn't be enclosed, even if
    18491859        both surrounding characters need to be.)</para>
    1850         <para>Older POSIX code tends to use lower-case exclusively for
     1860      <para>Older POSIX code tends to use lower-case exclusively for
    18511861        type, record, and field names; there are only a few cases in
    18521862        the &CCL; sources where mixed-case names need to be
    18531863        escaped.</para>
    1854        
    1855       </sect2>
    1856 
    1857       <sect2 id="Examples--1-">
    1858         <title>Examples</title>
    1859         <programlisting>
    1860 ;;; Allocate a record of type "window".
    1861 (rlet ((w :window)) ...)
    1862 ;;; Allocate a record of type "Window", which is probably a
    1863 ;;;  different type
    1864 (rlet ((w :&lt;w&gt;indow)) ...)
    1865 ;;; This is equivalent to the last example
    1866 (rlet ((w :&lt;w&gt;INDOW)))
    1867 </programlisting>
    1868       </sect2>
    1869     </sect1>
    1870 
    1871     <sect1 id="Reading-Foreign-Names">
    1872       <title>Reading Foreign Names</title> <para>Clozure Common Lisp
     1864         
     1865    </sect2>
     1866
     1867    <sect2 id="Examples--1-">
     1868      <title>Examples</title>
     1869      <programlisting>
     1870        ;;; Allocate a record of type "window".
     1871        (rlet ((w :window)) ...)
     1872        ;;; Allocate a record of type "Window", which is probably a
     1873        ;;;  different type
     1874        (rlet ((w :&lt;w&gt;indow)) ...)
     1875        ;;; This is equivalent to the last example
     1876        (rlet ((w :&lt;w&gt;INDOW)))
     1877      </programlisting>
     1878    </sect2>
     1879  </sect1>
     1880
     1881  <!-- ******************************************  -->
     1882  <sect1 id="Reading-Foreign-Names">
     1883    <title>Reading Foreign Names</title> <para>Clozure Common Lisp
    18731884      provides several reader macros to make it more convenient to
    18741885      handle foreign type, function, variable, and constant
     
    18801891      frameworks.</para>
    18811892
    1882       <para>These reader macros include "#_" to read foreign function
     1893    <para>These reader macros include "#_" to read foreign function
    18831894      names, "#&amp;" to read foreign variable names (note that in
    18841895      earlier versions of OpenMCL the reader macro "#?" was used for
     
    18881899      accessors.</para>
    18891900
    1890       <para>All of these reader macros preserve the case of the text
     1901    <para>All of these reader macros preserve the case of the text
    18911902      that they read; beyond that similarity, each performs some
    18921903      additional work, unique to each reader macro, to create symbols
     
    18971908      "NEXTSTEP-FUNCTIONS" package.</para>
    18981909
    1899       <para>You are likely to see these reader macros used extensively
     1910    <para>You are likely to see these reader macros used extensively
    19001911      in Lisp code that works with foreign libraries; for example,
    19011912      Clozure CL IDE code, which defines numerous Objective-C classes
    19021913      and methods, uses these reader macros extensively.</para>
    19031914
    1904       <para>For more detailed descriptions of each of these reader
     1915    <para>For more detailed descriptions of each of these reader
    19051916      macros, see the Foreign-Function-Interface Dictionary
    19061917      section.</para>
    1907     </sect1>
    1908 
    1909     <sect1 id="Tutorial--Using-Basic-Calls-and-Types">
    1910       <title>Tutorial: Using Basic Calls and Types</title>
    1911       <para>This tutorial is meant to cover the basics of &CCL; for
     1918  </sect1>
     1919
     1920  <!-- ******************************************  -->
     1921  <sect1 id="Tutorial--Using-Basic-Calls-and-Types">
     1922    <title>Tutorial: Using Basic Calls and Types</title>
     1923    <para>This tutorial is meant to cover the basics of &CCL; for
    19121924      calling external C functions and passing data back and forth.
    19131925      These basics will provide the foundation for more advanced
    19141926      techniques which will allow access to the various external
    19151927      libraries and toolkits.</para>
    1916       <para>The first step is to start with a simple C dynamic library
     1928    <para>The first step is to start with a simple C dynamic library
    19171929      in order to actually observe what is actually passing between
    19181930      &CCL; and C.  So, some C code is in order:</para>
    1919       <para>Create the file typetest.c, and put the following code
     1931    <para>Create the file typetest.c, and put the following code
    19201932      into it:</para>
    1921       <programlisting>
    1922 
     1933    <programlisting>
    19231934#include &lt;stdio.&gt;
    19241935
     
    19501961    return data;
    19511962}
    1952       </programlisting>
    1953       <para>This defines three functions.  If you're familiar with C,
     1963    </programlisting>
     1964    <para>This defines three functions.  If you're familiar with C,
    19541965      notice that there's no <literal>main()</literal>, because we're
    19551966      just building a library, not an executable.</para>
    1956       <para>The function <literal>void_void_test()</literal> doesn't
     1967    <para>The function <literal>void_void_test()</literal> doesn't
    19571968      take any parameters, and doesn't return anything, but it prints
    19581969      two lines to let us know it was called.
     
    19631974      really can call C functions, pass them values, and get values
    19641975      back from them.</para>
    1965       <para>This code is compiled into a dynamic library on OS X
     1976    <para>This code is compiled into a dynamic library on OS X
    19661977      10.3.4 with the command:</para>
    1967       <programlisting>
    1968 
    1969 gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
    1970     -install_name ./libtypetest.dylib
    1971       </programlisting>
    1972       <tip><para>Users of 64-bit platforms may need to pass options such
    1973       as "-m64" to gcc, may need to give the output library a different
    1974       extension (such as ".so"), and may need to user slightly different
    1975       values for other options in order to create an equivalent test
    1976       library.</para></tip>
    1977 
    1978       <para>The -dynamiclib tells gcc that we will be compiling this
     1978    <programlisting>
     1979
     1980      gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
     1981      -install_name ./libtypetest.dylib
     1982    </programlisting>
     1983    <tip><para>Users of 64-bit platforms may need to pass options such
     1984        as "-m64" to gcc, may need to give the output library a different
     1985        extension (such as ".so"), and may need to user slightly different
     1986        values for other options in order to create an equivalent test
     1987        library.</para></tip>
     1988
     1989    <para>The -dynamiclib tells gcc that we will be compiling this
    19791990      into a dynamic library and not an executable binary program.
    19801991      The output filename is "libtypetest.dylib".  Notice that we
     
    19831994      the library.  &CCL; doesn't need it to be this way, but it is
    19841995      a good idea to adhere to existing conventions.</para>
    1985       <para>The -install_name flag is primarily used when building OS
     1996    <para>The -install_name flag is primarily used when building OS
    19861997      X "bundles".  In this case, we are not using it, so we put a
    19871998      placeholder into it, "./libtypetest.dylib".  If we wanted to use
    19881999      typetest in a bundle, the -install_name argument would be a
    19892000      relative path from some "current" directory.</para>
    1990       <para>After creating this library, the first step is to tell
     2001    <para>After creating this library, the first step is to tell
    19912002      &CCL; to open the dynamic library.  This is done by calling
    19922003      .</para>
    1993       <programlisting>
    1994 
    1995 Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
    1996 
    1997 ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
    1998 #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E&gt;
    1999 </programlisting>
    2000       <para>You should use an absolute path here; using a relative
     2004    <programlisting>
     2005
     2006      Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
     2007
     2008      ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
     2009      #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E&gt;
     2010    </programlisting>
     2011    <para>You should use an absolute path here; using a relative
    20012012      one, such as just "libtypetest.dylib", would appear to work, but
    20022013      there are subtle problems which occur after reloading it.  See
     
    20042015      because software should never rely on its starting directory
    20052016      being anything in particular.</para>
    2006       <para>This command returns a reference to the opened shared library, and
    2007 &CCL; also adds one to the global variable
    2008 <literal>ccl::*shared-libraries*</literal>:</para>
    2009       <programlisting>
    2010 
    2011 ? ccl::*shared-libraries*
    2012 (#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
    2013  #&lt;SHLIB /usr/lib/libSystem.B.dylib #x606179E>)
    2014       </programlisting>
    2015       <para>Before we call anything, let's check that the individual
     2017    <para>This command returns a reference to the opened shared library, and
     2018      &CCL; also adds one to the global variable
     2019      <literal>ccl::*shared-libraries*</literal>:</para>
     2020    <programlisting>
     2021
     2022      ? ccl::*shared-libraries*
     2023      (#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
     2024       #&lt;SHLIB /usr/lib/libSystem.B.dylib #x606179E>)
     2025    </programlisting>
     2026    <para>Before we call anything, let's check that the individual
    20162027      functions can actually be found by the system.  We don't have to
    20172028      do this, but it helps to know how to find out whether this is
    20182029      the problem, when something goes wrong.  We use <xref
    2019       linkend="m_external-call"/>:</para>
    2020       <programlisting>
    2021 
    2022 ? (external "_void_void_test")
    2023 #&lt;EXTERNAL-ENTRY-POINT "_void_void_test" (#x000CFDF8) /Users/andewl/openmcl/libtypetest.dylib #x638EDF6>
    2024 
    2025 ? (external "_sc_sc_test")
    2026 #&lt;EXTERNAL-ENTRY-POINT "_sc_sc_test" (#x000CFE50) /Users/andewl/openmcl/libtypetest.dylib #x638EB3E>
    2027 
    2028 ? (external "_uc_uc_test")
    2029 #&lt;EXTERNAL-ENTRY-POINT "_uc_uc_test" (#x000CFED4) /Users/andewl/openmcl/libtypetest.dylib #x638E626>
    2030       </programlisting>
    2031       <para>Notice that the actual function names have been "mangled"
     2030                                                         linkend="m_external-call"/>:</para>
     2031    <programlisting>
     2032
     2033      ? (external "_void_void_test")
     2034      #&lt;EXTERNAL-ENTRY-POINT "_void_void_test" (#x000CFDF8) /Users/andewl/openmcl/libtypetest.dylib #x638EDF6>
     2035
     2036      ? (external "_sc_sc_test")
     2037      #&lt;EXTERNAL-ENTRY-POINT "_sc_sc_test" (#x000CFE50) /Users/andewl/openmcl/libtypetest.dylib #x638EB3E>
     2038
     2039      ? (external "_uc_uc_test")
     2040      #&lt;EXTERNAL-ENTRY-POINT "_uc_uc_test" (#x000CFED4) /Users/andewl/openmcl/libtypetest.dylib #x638E626>
     2041    </programlisting>
     2042    <para>Notice that the actual function names have been "mangled"
    20322043      by the C linker.  The first function was named "void_void_test"
    20332044      in typetest.c, but in libtypetest.dylib, it has an underscore (a
     
    20362047      changed - may be different for other operating systems or other
    20372048      versions, so you need to "just know" how it's done...</para>
    2038       <para>Also, pay particular attention to the fact that a
     2049    <para>Also, pay particular attention to the fact that a
    20392050      hexadecimal value appears in the EXTERNAL-ENTRY-POINT.
    20402051      (#x000CFDF8, for example - but what it is doesn't matter.)
     
    20422053      Functions which aren't found will not have a hex number.  For
    20432054      example:</para>
    2044       <programlisting>
    2045 
    2046 ? (external "functiondoesnotexist")
    2047 #&lt;EXTERNAL-ENTRY-POINT "functiondoesnotexist" {unresolved}  #x638E3F6>
    2048 </programlisting>
    2049       <para>The "unresolved" tells us that &CCL; wasn't able to find this
     2055    <programlisting>
     2056
     2057      ? (external "functiondoesnotexist")
     2058      #&lt;EXTERNAL-ENTRY-POINT "functiondoesnotexist" {unresolved}  #x638E3F6>
     2059    </programlisting>
     2060    <para>The "unresolved" tells us that &CCL; wasn't able to find this
    20502061      function, which means you would get an error, "Can't resolve foreign
    20512062      symbol," if you tried to call it.</para>
    2052       <para>These external function references also are stored in a
     2063    <para>These external function references also are stored in a
    20532064      hash table which is accessible through a global variable,
    20542065      <literal>ccl::*eeps*</literal>.</para>
    2055       <para>At this point, we are ready to try our first external
     2066    <para>At this point, we are ready to try our first external
    20562067      function call:</para>
    2057       <programlisting>
    2058 
    2059 ? (external-call "_void_void_test" :void)
    2060 Entered void_void_test:
    2061 Exited  void_void_test:
    2062 NIL
    2063       </programlisting>
    2064       <para>We used , which is is the normal mechanism for accessing
     2068    <programlisting>
     2069
     2070      ? (external-call "_void_void_test" :void)
     2071      Entered void_void_test:
     2072      Exited  void_void_test:
     2073      NIL
     2074    </programlisting>
     2075    <para>We used , which is is the normal mechanism for accessing
    20652076      externally linked code.  The "_void_void_test" is the mangled
    20662077      name of the external function.  The :void refers to the return
    20672078      type of the function.</para>
    2068       <para>The next step is to try passing a value to C, and getting one
    2069 back:</para>
    2070       <programlisting>
    2071 
    2072 ? (external-call "_sc_sc_test" :signed-byte -128 :signed-byte)
    2073 Entered sc_sc_test:
    2074 Data In: -128
    2075 Exited  sc_sc_test:
    2076 -128
    2077 </programlisting>
    2078       <para>The first :signed-byte gives the type of the first
     2079    <para>The next step is to try passing a value to C, and getting one
     2080      back:</para>
     2081    <programlisting>
     2082
     2083      ? (external-call "_sc_sc_test" :signed-byte -128 :signed-byte)
     2084      Entered sc_sc_test:
     2085      Data In: -128
     2086      Exited  sc_sc_test:
     2087      -128
     2088    </programlisting>
     2089    <para>The first :signed-byte gives the type of the first
    20792090      argument, and then -128 gives the value to pass for it.  The
    20802091      second :signed-byte gives the return type.  The return type is
    20812092      always given by the last argument to .</para>
    2082       <para>Everything looks good.  Now, let's try a number outside
     2093    <para>Everything looks good.  Now, let's try a number outside
    20832094      the range which fits in one byte:</para>
    2084       <programlisting>
    2085 
    2086 ? (external-call "_sc_sc_test" :signed-byte -567 :signed-byte)
    2087 Entered sc_sc_test:
    2088 Data In: -55
    2089 Exited  sc_sc_test:
    2090 -55
    2091 </programlisting>
    2092       <para>Hmmmm.  A little odd.  Let's look at the unsigned stuff to
     2095    <programlisting>
     2096
     2097      ? (external-call "_sc_sc_test" :signed-byte -567 :signed-byte)
     2098      Entered sc_sc_test:
     2099      Data In: -55
     2100      Exited  sc_sc_test:
     2101      -55
     2102    </programlisting>
     2103    <para>Hmmmm.  A little odd.  Let's look at the unsigned stuff to
    20932104      see how it reacts:</para>
    2094       <programlisting>
    2095 
    2096 ? (external-call "_uc_uc_test" :unsigned-byte 255 :unsigned-byte)
    2097 Entered uc_uc_test:
    2098 Data In: 255
    2099 Exited  uc_uc_test:
    2100 255
    2101 </programlisting>
    2102       <para>That looks okay.  Now, let's go outside the valid range again:</para>
    2103       <programlisting>
    2104 
    2105 ? (external-call "_uc_uc_test" :unsigned-byte 567 :unsigned-byte)
    2106 Entered uc_uc_test:
    2107 Data In: 55
    2108 Exited  uc_uc_test:
    2109 55
    2110 
    2111 ? (external-call "_uc_uc_test" :unsigned-byte -567 :unsigned-byte)
    2112 Entered uc_uc_test:
    2113 Data In: 201
    2114 Exited  uc_uc_test:
    2115 201
    2116       </programlisting>
    2117       <para>Since a signed byte can only hold values from -128 through 127, and
     2105    <programlisting>
     2106
     2107      ? (external-call "_uc_uc_test" :unsigned-byte 255 :unsigned-byte)
     2108      Entered uc_uc_test:
     2109      Data In: 255
     2110      Exited  uc_uc_test:
     2111      255
     2112    </programlisting>
     2113    <para>That looks okay.  Now, let's go outside the valid range again:</para>
     2114    <programlisting>
     2115
     2116      ? (external-call "_uc_uc_test" :unsigned-byte 567 :unsigned-byte)
     2117      Entered uc_uc_test:
     2118      Data In: 55
     2119      Exited  uc_uc_test:
     2120      55
     2121
     2122      ? (external-call "_uc_uc_test" :unsigned-byte -567 :unsigned-byte)
     2123      Entered uc_uc_test:
     2124      Data In: 201
     2125      Exited  uc_uc_test:
     2126      201
     2127    </programlisting>
     2128    <para>Since a signed byte can only hold values from -128 through 127, and
    21182129      an unsigned one can only hold values from 0 through 255, any number
    21192130      outside that range gets "clipped": only the low eight bits of it
    21202131      are used.</para>
    2121       <para>What is important to remember is that <emphasis>external
    2122       function calls have
    2123       very few safety checks.</emphasis>
     2132    <para>What is important to remember is that <emphasis>external
     2133        function calls have
     2134        very few safety checks.</emphasis>
    21242135      Data outside the valid range for its type will silently do
    21252136      very strange things; pointers outside the valid range can very well
    21262137      crash the system.</para>
    2127       <para>That's it for our first example library.  If you're still
     2138    <para>That's it for our first example library.  If you're still
    21282139      following along, let's add some more C code to look at the rest
    21292140      of the primitive types.  Then we'll need to recompile the
    21302141      dynamic library, load it again, and then we can see what
    21312142      happens.</para>
    2132       <para>Add the following code to typetest.c:</para>
    2133       <programlisting>
    2134 
     2143    <para>Add the following code to typetest.c:</para>
     2144    <programlisting>
    21352145int
    21362146si_si_test(int data)
     
    21822192    return data;
    21832193}
    2184 </programlisting>
    2185       <para>The command line to compile the dynamic library is the same as before:</para>
    2186       <programlisting>
    2187 
    2188 gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
    2189     -install_name ./libtypetest.dylib
    2190 </programlisting>
    2191       <para>Now, restart &CCL;.  This step is required because
     2194    </programlisting>
     2195    <para>The command line to compile the dynamic library is the same as before:</para>
     2196    <programlisting>
     2197
     2198      gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
     2199      -install_name ./libtypetest.dylib
     2200    </programlisting>
     2201    <para>Now, restart &CCL;.  This step is required because
    21922202      &CCL; cannot close and reload a dynamic library on OS
    21932203      X.</para>
    2194       <para>Have you restarted?  Okay, try out the new code:</para>
    2195       <programlisting>
    2196 
    2197 Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
    2198 
    2199 ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
    2200 #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
    2201 
    2202 ? (external-call "_si_si_test" :signed-fullword -178965 :signed-fullword)
    2203 Entered si_si_test:
    2204 Data In: -178965
    2205 Exited  si_si_test:
    2206 -178965
    2207 
    2208 ? ;; long is the same size as int on 32-bit machines.
    2209 (external-call "_sl_sl_test" :signed-fullword -178965 :signed-fullword)
    2210 Entered sl_sl_test:
    2211 Data In: -178965
    2212 Exited  sl_sl_test:
    2213 -178965
    2214 
    2215 ? (external-call "_sll_sll_test"
    2216                  :signed-doubleword -973891578912 :signed-doubleword)
    2217 Entered sll_sll_test:
    2218 Data In: -973891578912
    2219 Exited  sll_sll_test:
    2220 -973891578912
    2221 </programlisting>
    2222       <para>Okay, everything seems to be acting as expected.  However,
     2204    <para>Have you restarted?  Okay, try out the new code:</para>
     2205    <programlisting>
     2206
     2207      Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
     2208
     2209      ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
     2210      #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
     2211
     2212      ? (external-call "_si_si_test" :signed-fullword -178965 :signed-fullword)
     2213      Entered si_si_test:
     2214      Data In: -178965
     2215      Exited  si_si_test:
     2216      -178965
     2217
     2218      ? ;; long is the same size as int on 32-bit machines.
     2219      (external-call "_sl_sl_test" :signed-fullword -178965 :signed-fullword)
     2220      Entered sl_sl_test:
     2221      Data In: -178965
     2222      Exited  sl_sl_test:
     2223      -178965
     2224
     2225      ? (external-call "_sll_sll_test"
     2226      :signed-doubleword -973891578912 :signed-doubleword)
     2227      Entered sll_sll_test:
     2228      Data In: -973891578912
     2229      Exited  sll_sll_test:
     2230      -973891578912
     2231    </programlisting>
     2232    <para>Okay, everything seems to be acting as expected.  However,
    22232233      just to remind you that most of this stuff has no safety net,
    22242234      here's what happens if somebody mistakes
     
    22262236      <literal>sll_sll_test()</literal>, thinking that a long is
    22272237      actually a doubleword:</para>
    2228       <programlisting>
    2229 
    2230 ? (external-call "_sl_sl_test"
    2231                  :signed-doubleword -973891578912 :signed-doubleword)
    2232 Entered sl_sl_test:
    2233 Data In: -227
    2234 Exited  sl_sl_test:
    2235 -974957576192
    2236       </programlisting>
    2237       <para>Ouch.  The C function changes the value with no warning
     2238    <programlisting>
     2239
     2240      ? (external-call "_sl_sl_test"
     2241      :signed-doubleword -973891578912 :signed-doubleword)
     2242      Entered sl_sl_test:
     2243      Data In: -227
     2244      Exited  sl_sl_test:
     2245      -974957576192
     2246    </programlisting>
     2247    <para>Ouch.  The C function changes the value with no warning
    22382248      that something is wrong.  Even worse, it manages to pass the
    22392249      original value back to &CCL;, which hides the fact that
    22402250      something is wrong.</para>
    2241       <para>Finally, let's take a look at doing this with
     2251    <para>Finally, let's take a look at doing this with
    22422252      floating-point numbers.</para>
    2243       <programlisting>
    2244 
    2245 Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
    2246 
    2247 ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
    2248 #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
    2249 
    2250 ? (external-call "_f_f_test" :single-float -1.256791e+11 :single-float)
    2251 Entered f_f_test:
    2252 Data In: -1.256791e+11
    2253 Exited  f_f_test:
    2254 -1.256791E+11
    2255 
    2256 ? (external-call "_d_d_test" :double-float -1.256791d+290 :double-float)
    2257 Entered d_d_test:
    2258 Data In: -1.256791e+290
    2259 Exited  d_d_test:
    2260 -1.256791D+290
    2261       </programlisting>
    2262       <para>Notice that the number ends with "...e+11" for the single-float,
    2263 and "...d+290" for the
    2264 double-float.  Lisp has both of these float types itself, and the
    2265 d instead of the e is how you specify which to create.  If
    2266 you tried to pass :double-float 1.0e2 to external-call, Lisp would
    2267 be nice enough to notice and give you a type error.  Don't get the
    2268 :double-float wrong, though, because then there's no protection.</para>
    2269       <para>Congratulations!  You now know how to call external C functions from
    2270 within &CCL;, and pass numbers back and forth.  Now that the basic
    2271 mechanics of calling and passing work, the next step is to examine how
    2272 to pass more complex data structures around.</para>
    2273 
    2274       <sect2 id="Acknowledgement">
    2275         <title>Acknowledgement</title>
    2276         <para>This chapter was generously contributed by Andrew
    2277         P. Lentvorski Jr.</para>
    2278       </sect2>
    2279     </sect1>
    2280 
    2281     <sect1 id="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap">
    2282       <title>Tutorial: Allocating Foreign Data on the Lisp Heap </title>
    2283       <para>Not every foreign function is so marvelously easy to use
     2253    <programlisting>
     2254
     2255      Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
     2256
     2257      ? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
     2258      #&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
     2259
     2260      ? (external-call "_f_f_test" :single-float -1.256791e+11 :single-float)
     2261      Entered f_f_test:
     2262      Data In: -1.256791e+11
     2263      Exited  f_f_test:
     2264      -1.256791E+11
     2265
     2266      ? (external-call "_d_d_test" :double-float -1.256791d+290 :double-float)
     2267      Entered d_d_test:
     2268      Data In: -1.256791e+290
     2269      Exited  d_d_test:
     2270      -1.256791D+290
     2271    </programlisting>
     2272    <para>Notice that the number ends with "...e+11" for the single-float,
     2273      and "...d+290" for the
     2274      double-float.  Lisp has both of these float types itself, and the
     2275      d instead of the e is how you specify which to create.  If
     2276      you tried to pass :double-float 1.0e2 to external-call, Lisp would
     2277      be nice enough to notice and give you a type error.  Don't get the
     2278      :double-float wrong, though, because then there's no protection.</para>
     2279    <para>Congratulations!  You now know how to call external C functions from
     2280      within &CCL;, and pass numbers back and forth.  Now that the basic
     2281      mechanics of calling and passing work, the next step is to examine how
     2282      to pass more complex data structures around.</para>
     2283
     2284    <sect2 id="Acknowledgement">
     2285      <title>Acknowledgement</title>
     2286          <para>This chapter was generously contributed by Andrew
     2287            P. Lentvorski Jr.</para>
     2288    </sect2>
     2289  </sect1>
     2290
     2291  <!-- ******************************************  -->
     2292  <sect1 id="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap">
     2293    <title>Tutorial: Allocating Foreign Data on the Lisp Heap </title>
     2294    <para>Not every foreign function is so marvelously easy to use
    22842295      as the ones we saw in the last section.  Some of them require
    22852296      you to allocate a C struct, fill it in with your own
     
    22872298      require you to allocate an empty struct so they can fill it in,
    22882299      and then you can read the information out of it.</para>
    2289       <para>Also, some of them have their own structs and return a
     2300    <para>Also, some of them have their own structs and return a
    22902301      pointer to that same struct every time you call them, but those
    22912302      are easier to deal with, so they won't be covered in this
    22922303      section.</para>
    2293       <para>You might know that Lisp (and, indeed, most programming
     2304    <para>You might know that Lisp (and, indeed, most programming
    22942305      languages) has two separate regions of memory.  There's the
    22952306      stack, which is where variable bindings are kept.  Memory on the
     
    22992310      only one thread.  If that's all you need, you can do it with
    23002311      .</para>
    2301       <para>Then, there's the heap, which holds everything else, and
     2312    <para>Then, there's the heap, which holds everything else, and
    23022313      is our subject here.  There are two advantages and one big
    23032314      disadvantage to putting things on the heap rather than the
     
    23072318      threads. Also, some data may be too large to copy multiple times
    23082319      or may be too large to allocate on the stack.</para>
    2309       <para>The second advantage is security.  If incoming data is
     2320    <para>The second advantage is security.  If incoming data is
    23102321      being placed directly onto the stack, the input data can cause
    23112322      stack overflows and underflows.  This is not something which
     
    23162327      always a bad idea; however, allocating it into the heap at least
    23172328      offers more protection than direct stack allocation.</para>
    2318       <para>The big disadvantage to allocating data on the heap is
     2329    <para>The big disadvantage to allocating data on the heap is
    23192330      that it must be explicitly deallocated - you need to "free" it
    23202331      when you're done with it.  Ordinarily, in Lisp, you wouldn't
     
    23242335      management becomes a manual process, just like in C and
    23252336      C++.</para>
    2326       <para>What that means is that, if you allocate something and
     2337    <para>What that means is that, if you allocate something and
    23272338      then lose track of the pointer to it, there's no way to ever
    23282339      free that memory.  That's what's called a memory leak, and if
     
    23302341      of it!  So, you need to be careful to not lose your
    23312342      pointers.</para>
    2332       <para>That disadvantage, though, is also an advantage for using
     2343    <para>That disadvantage, though, is also an advantage for using
    23332344      foreign functions.  Since the garbage collector doesn't know
    23342345      about this memory, it will never move it around.  External C
     
    23432354      anything pointing back and saying "you deallocated this too
    23442355      soon."</para>
    2345       <para>And, so, on to the code...</para>
    2346       <para>As in the last tutorial, our first step
     2356    <para>And, so, on to the code...</para>
     2357    <para>As in the last tutorial, our first step
    23472358      is to create a local dynamic library in order to help show
    23482359      what is actually going on between &CCL; and C.  So, create the file
    23492360      ptrtest.c, with the following code:</para>
    2350       <programlisting>
     2361    <programlisting>
    23512362#include &lt;stdio.h&gt;
    23522363
    23532364void reverse_int_array(int * data, unsigned int dataobjs)
    23542365{
    2355   int i, t;
    2356 
    2357   for(i=0; i&lt;dataobjs/2; i++)
    2358     {
    2359       t = *(data+i);
    2360       *(data+i) = *(data+dataobjs-1-i);
    2361       *(data+dataobjs-1-i) = t;
    2362     }
     2366    int i, t;
     2367   
     2368    for(i=0; i&lt;dataobjs/2; i++)
     2369        {
     2370            t = *(data+i);
     2371            *(data+i) = *(data+dataobjs-1-i);
     2372            *(data+dataobjs-1-i) = t;
     2373        }
    23632374}
    23642375
    23652376void reverse_int_ptr_array(int **ptrs, unsigned int ptrobjs)
    23662377{
    2367   int *t;
    2368   int i;
    2369 
    2370   for(i=0; i&lt;ptrobjs/2; i++)
    2371     {
    2372       t = *(ptrs+i);
    2373       *(ptrs+i) = *(ptrs+ptrobjs-1-i);
    2374       *(ptrs+ptrobjs-1-i) = t;
    2375     }
     2378    int *t;
     2379    int i;
     2380   
     2381    for(i=0; i&lt;ptrobjs/2; i++)
     2382        {
     2383            t = *(ptrs+i);
     2384            *(ptrs+i) = *(ptrs+ptrobjs-1-i);
     2385            *(ptrs+ptrobjs-1-i) = t;
     2386        }
    23762387}
    23772388
     
    23792390reverse_int_ptr_ptrtest(int **ptrs)
    23802391{
    2381   reverse_int_ptr_array(ptrs, 2);
    2382 
    2383   reverse_int_array(*(ptrs+0), 4);
    2384   reverse_int_array(*(ptrs+1), 4);
     2392    reverse_int_ptr_array(ptrs, 2);
     2393   
     2394    reverse_int_array(*(ptrs+0), 4);
     2395    reverse_int_array(*(ptrs+1), 4);
    23852396}
    2386       </programlisting>
    2387       <para>This defines three functions.
     2397    </programlisting>
     2398    <para>This defines three functions.
    23882399      <literal>reverse_int_array</literal> takes a pointer to an array
    23892400      of <literal>int</literal>s, and a count telling how many items
     
    24002411      pointers, then it reverses each of the two arrays of
    24012412      <literal>int</literal>s.</para>
    2402       <para>Now, compile ptrtest.c into a dynamic library using the
     2413    <para>Now, compile ptrtest.c into a dynamic library using the
    24032414      command:</para>
    2404       <programlisting>
    2405 gcc -dynamiclib -Wall -o libptrtest.dylib ptrtest.c -install_name ./libptrtest.dylib
    2406       </programlisting>
    2407       <para>If that command doesn't make sense to you, feel free to go back
    2408 and read about it at .</para>
    2409       <para>Now, start &CCL; and enter:</para>
    2410       <programlisting>
    2411 ? ;; make-heap-ivector courtesy of Gary Byers
    2412 (defun make-heap-ivector (element-count element-type)
    2413   (let* ((subtag (ccl::element-type-subtype element-type)))
    2414     (unless (= (logand subtag target::fulltagmask)
    2415                target::fulltag-immheader)
    2416       (error "~s is not an ivector subtype." element-type))
    2417     (let* ((size-in-bytes (ccl::subtag-bytes subtag element-count)))
    2418       (ccl::%make-heap-ivector subtag size-in-bytes element-count))))
    2419 MAKE-HEAP-IVECTOR
    2420 
    2421 ? ;; dispose-heap-ivector created for symmetry
    2422 (defmacro dispose-heap-ivector (a mp)
    2423   `(progn
    2424      (ccl::%dispose-heap-ivector ,a)
    2425      ;; Demolish the arguments for safety
    2426      (setf ,a nil)
    2427      (setf ,mp nil)))
    2428 DISPOSE-HEAP-IVECTOR
    2429 </programlisting>
    2430       <para>If you don't understand how those functions do what they do.
     2415    <programlisting>
     2416      gcc -dynamiclib -Wall -o libptrtest.dylib ptrtest.c -install_name ./libptrtest.dylib
     2417    </programlisting>
     2418    <para>If that command doesn't make sense to you, feel free to go back
     2419      and read about it at .</para>
     2420    <para>Now, start &CCL; and enter:</para>
     2421    <programlisting>
     2422      ? ;; make-heap-ivector courtesy of Gary Byers
     2423      (defun make-heap-ivector (element-count element-type)
     2424       (let* ((subtag (ccl::element-type-subtype element-type)))
     2425        (unless (= (logand subtag target::fulltagmask)
     2426                 target::fulltag-immheader)
     2427         (error "~s is not an ivector subtype." element-type))
     2428        (let* ((size-in-bytes (ccl::subtag-bytes subtag element-count)))
     2429         (ccl::%make-heap-ivector subtag size-in-bytes element-count))))     
     2430      MAKE-HEAP-IVECTOR
     2431
     2432      ? ;; dispose-heap-ivector created for symmetry
     2433      (defmacro dispose-heap-ivector (a mp)
     2434       `(progn
     2435         (ccl::%dispose-heap-ivector ,a)
     2436         ;; Demolish the arguments for safety
     2437         (setf ,a nil)
     2438         (setf ,mp nil)))
     2439      DISPOSE-HEAP-IVECTOR
     2440    </programlisting>
     2441    <para>If you don't understand how those functions do what they do.
    24312442      That's okay; it gets into very fine detail which really doesn't
    24322443      matter, because you don't need to change them.</para>
    2433       <para>The function <literal>make-heap-ivector</literal> is the
     2444    <para>The function <literal>make-heap-ivector</literal> is the
    24342445      primary tool for allocating objects in heap memory.  It
    24352446      allocates a fixed-size &CCL; object in heap memory.  It
     
    24372448      &CCL;, and a <literal>macptr</literal>, which can be used to
    24382449      access the underlying memory directly.  For example:</para>
    2439       <programlisting>
    2440 ? ;; Create an array of 3 4-byte-long integers
    2441 (multiple-value-bind (la lap)
    2442     (make-heap-ivector 3 '(unsigned-byte 32))
    2443   (setq a la)
    2444   (setq ap lap))
    2445 ;Compiler warnings :
    2446 ;   Undeclared free variable A, in an anonymous lambda form.
    2447 ;   Undeclared free variable AP, in an anonymous lambda form.
    2448 #&lt;A Mac Pointer #x10217C>
    2449 
    2450 ? a
    2451 #(1396 2578 97862649)
    2452 
    2453 ? ap
    2454 #&lt;A Mac Pointer #x10217C>
    2455 </programlisting>
    2456       <para>It's important to realize that the contents of the
     2450    <programlisting>
     2451      ? ;; Create an array of 3 4-byte-long integers
     2452      (multiple-value-bind (la lap)
     2453          (make-heap-ivector 3 '(unsigned-byte 32))
     2454        (setq a la)
     2455        (setq ap lap))
     2456      ;Compiler warnings :
     2457      ;   Undeclared free variable A, in an anonymous lambda form.
     2458      ;   Undeclared free variable AP, in an anonymous lambda form.
     2459      #&lt;A Mac Pointer #x10217C>
     2460
     2461      ? a
     2462      #(1396 2578 97862649)
     2463
     2464      ? ap
     2465      #&lt;A Mac Pointer #x10217C>
     2466    </programlisting>
     2467    <para>It's important to realize that the contents of the
    24572468      <literal>ivector</literal> we've just created haven't been
    24582469      initialized, so their values are unpredictable, and you should
    24592470      be sure not to read from them before you set them, to avoid
    24602471      confusing results.</para>
    2461       <para>At this point, <literal>a</literal> references an object
     2472    <para>At this point, <literal>a</literal> references an object
    24622473      which works just like a normal array.  You can refer to any item
    24632474      of it with the standard <literal>aref</literal> function, and
     
    24652476      noted above, the <literal>ivector</literal>'s contents haven't
    24662477      been initialized, so that's the next order of business:</para>
    2467       <programlisting>
    2468 ? a
    2469 #(1396 2578 97862649)
    2470 
    2471 ? (aref a 2)
    2472 97862649
    2473 
    2474 ? (setf (aref a 0) 3)
    2475 3
    2476 
    2477 ? (setf (aref a 1) 4)
    2478 4
    2479 
    2480 ? (setf (aref a 2) 5)
    2481 5
    2482 
    2483 ? a
    2484 #(3 4 5)
    2485 </programlisting>
    2486       <para>In addition, the <literal>macptr</literal> allows direct
     2478    <programlisting>
     2479      ? a
     2480      #(1396 2578 97862649)
     2481
     2482      ? (aref a 2)
     2483      97862649
     2484
     2485      ? (setf (aref a 0) 3)
     2486      3
     2487
     2488      ? (setf (aref a 1) 4)
     2489      4
     2490
     2491      ? (setf (aref a 2) 5)
     2492      5
     2493
     2494      ? a
     2495      #(3 4 5)
     2496    </programlisting>
     2497    <para>In addition, the <literal>macptr</literal> allows direct
    24872498      access to the same memory:</para>
    2488       <programlisting>
    2489 ? (setq *byte-length-of-long* 4)
    2490 4
    2491 
    2492 ? (%get-signed-long ap (* 2 *byte-length-of-long*))
    2493 5
    2494 
    2495 ? (%get-signed-long ap (* 0 *byte-length-of-long*))
    2496 3
    2497 
    2498 ? (setf (%get-signed-long ap (* 0 *byte-length-of-long*)) 6)
    2499 6
    2500 
    2501 ? (setf (%get-signed-long ap (* 2 *byte-length-of-long*)) 7)
    2502 7
    2503 
    2504 ? ;; Show that a actually got changed through ap
    2505 a
    2506 #(6 4 7)
    2507       </programlisting>
    2508       <para>So far, there is nothing about this object that could not
     2499    <programlisting>
     2500      ? (setq *byte-length-of-long* 4)
     2501      4
     2502
     2503      ? (%get-signed-long ap (* 2 *byte-length-of-long*))
     2504      5
     2505
     2506      ? (%get-signed-long ap (* 0 *byte-length-of-long*))
     2507      3
     2508
     2509      ? (setf (%get-signed-long ap (* 0 *byte-length-of-long*)) 6)
     2510      6
     2511
     2512      ? (setf (%get-signed-long ap (* 2 *byte-length-of-long*)) 7)
     2513      7
     2514
     2515      ? ;; Show that a actually got changed through ap
     2516      a
     2517      #(6 4 7)
     2518    </programlisting>
     2519    <para>So far, there is nothing about this object that could not
    25092520      be done much better with standard Lisp.  However, the
    25102521      <literal>macptr</literal> can be used to pass this chunk of
    25112522      memory off to a C function.  Let's use the C code to reverse the
    25122523      elements in the array:</para>
    2513       <programlisting>
    2514 ? ;; Insert the full path to your copy of libptrtest.dylib
    2515 (open-shared-library "/Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib")
    2516 #&lt;SHLIB /Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib #x639D1E6>
    2517 
    2518 ? a
    2519 #(6 4 7)
    2520 
    2521 ? ap
    2522 #&lt;A Mac Pointer #x10217C>
    2523 
    2524 ? (external-call "_reverse_int_array" :address ap :unsigned-int (length a) :address)
    2525 #&lt;A Mac Pointer #x10217C>
    2526 
    2527 ? a
    2528 #(7 4 6)
    2529 
    2530 ? ap
    2531 #&lt;A Mac Pointer #x10217C>
    2532 </programlisting>
    2533       <para>The array gets passed correctly to the C function,
     2524    <programlisting>
     2525      ? ;; Insert the full path to your copy of libptrtest.dylib
     2526      (open-shared-library "/Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib")
     2527      #&lt;SHLIB /Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib #x639D1E6>
     2528
     2529      ? a
     2530      #(6 4 7)
     2531
     2532      ? ap
     2533      #&lt;A Mac Pointer #x10217C>
     2534
     2535      ? (external-call "_reverse_int_array" :address ap :unsigned-int (length a) :address)
     2536      #&lt;A Mac Pointer #x10217C>
     2537
     2538      ? a
     2539      #(7 4 6)
     2540
     2541      ? ap
     2542      #&lt;A Mac Pointer #x10217C>
     2543    </programlisting>
     2544    <para>The array gets passed correctly to the C function,
    25342545      <literal>reverse_int_array</literal>.  The C function reverses
    25352546      the contents of the array in-place; that is, it doesn't make a
     
    25382549      the allocated array memory has been directly modifed, &CCL;
    25392550      reflects those changes directly in the array as well.</para>
    2540       <para>There is one final bit of housekeeping to deal with.
     2551    <para>There is one final bit of housekeeping to deal with.
    25412552      Before moving on, the memory needs to be deallocated:</para>
    2542       <programlisting>
    2543 ? ;; dispose-heap-ivector created for symmetry
    2544 ;; Macro repeated here for pedagogy
    2545 (defmacro dispose-heap-ivector (a mp)
    2546   `(progn
    2547      (ccl::%dispose-heap-ivector ,a)
    2548      ;; Demolish the arguments for safety
    2549      (setf ,a nil)
    2550      (setf ,mp nil)))
    2551 DISPOSE-HEAP-IVECTOR
    2552 
    2553 ? (dispose-heap-ivector a ap)
    2554 NIL
    2555 
    2556 ? a
    2557 NIL
    2558 
    2559 ? ap
    2560 NIL
    2561 </programlisting>
    2562       <para>The <literal>dispose-heap-ivector</literal> macro actually
     2553    <programlisting>
     2554      ? ;; dispose-heap-ivector created for symmetry
     2555      ;; Macro repeated here for pedagogy
     2556      (defmacro dispose-heap-ivector (a mp)
     2557      `(progn
     2558      (ccl::%dispose-heap-ivector ,a)
     2559      ;; Demolish the arguments for safety
     2560      (setf ,a nil)
     2561      (setf ,mp nil)))
     2562      DISPOSE-HEAP-IVECTOR
     2563
     2564      ? (dispose-heap-ivector a ap)
     2565      NIL
     2566
     2567      ? a
     2568      NIL
     2569
     2570      ? ap
     2571      NIL
     2572    </programlisting>
     2573    <para>The <literal>dispose-heap-ivector</literal> macro actually
    25632574      deallocates the ivector, releasing its memory into the heap for
    25642575      something else to use.  In addition, it makes sure that the
     
    25682579      Making sure there are no other variables set to it is up to
    25692580      you.</para>
    2570       <para>When do you call <literal>dispose-heap-ivector</literal>?
     2581    <para>When do you call <literal>dispose-heap-ivector</literal>?
    25712582      Anytime after you know the ivector will never be used again, but
    25722583      no sooner.  If you have a lot of ivectors, say, in a hash table,
     
    25762587      course!  Exactly what strategy to take depends on the situation,
    25772588      so just try to keep things simple unless you know better.</para>
    2578       <para>The simplest situation is when you have things set up so
     2589    <para>The simplest situation is when you have things set up so
    25792590      that a Lisp object "encapsulates" a pointer to foreign data,
    25802591      taking care of all the details of using it.  In this case, you
     
    25842595      data doesn't get deallocated while your Lisp object still refers
    25852596      to it.</para>
    2586       <para>If you're willing to accept a few limitations, you can
     2597    <para>If you're willing to accept a few limitations, you can
    25872598      make this easy.  First, you can't let foreign code keep a
    25882599      permanent pointer to the memory; it has to always finish what
     
    25922603      nothing, either foreign code or Lisp code, should explicitly
    25932604      deallocate the memory.</para>
    2594       <para>If you can make sure all of these are true, you can at
     2605    <para>If you can make sure all of these are true, you can at
    25952606      least ensure that the foreign pointer is deallocated when the
    25962607      encapsulating object is about to become garbage, by using
     
    25982609      essentially the same as what Java and other languages call
    25992610      "finialization".</para>
    2600       <para>Termination is a way of asking the garbage collector to
     2611    <para>Termination is a way of asking the garbage collector to
    26012612      let you know when it's about to destroy an object which isn't
    26022613      used anymore.  Before destroying the object, it calls a function
    26032614      which you write, called a terminator.</para>
    2604       <para>So, you can use termination to find out when a particular
     2615    <para>So, you can use termination to find out when a particular
    26052616      <literal>macptr</literal> is about to become garbage.  That's
    26062617      not quite as helpful as it might seem: It's not exactly the same
     
    26142625      functions don't, but it's not hard to think of
    26152626      exceptions.</para>
    2616       <para>You can use code such as this to make all this happen:</para>
    2617       <programlisting>
    2618 (defclass wrapper (whatever)
    2619   ((element-type :initarg :element-type)
    2620    (element-count :initarg :element-count)
    2621    (ivector)
    2622    (macptr)))
    2623 
    2624 (defmethod initialize-instance ((wrapper wrapper) &amp;rest initargs)
    2625   (declare (ignore initargs))
    2626   (call-next-method)
    2627   (ccl:terminate-when-unreachable wrapper)
    2628   (with-slots (ivector macptr element-type element-count) wrapper
    2629     (multiple-value-bind (new-ivector new-macptr)
    2630         (make-heap-ivector element-count element-type)
    2631       (setq ivector new-ivector
    2632             macptr new-macptr))))
    2633 
    2634 (defmethod ccl:terminate ((wrapper wrapper))
    2635   (with-slots (ivector macptr) wrapper
    2636     (when ivector
    2637       (dispose-heap-ivector ivector macptr)
    2638       (setq ivector nil
    2639             macptr nil))))
    2640       </programlisting>
    2641       <para>The <literal>ccl:terminate</literal> method will be called
     2627    <para>You can use code such as this to make all this happen:</para>
     2628    <programlisting>
     2629      (defclass wrapper (whatever)
     2630        ((element-type :initarg :element-type)
     2631         (element-count :initarg :element-count)
     2632         (ivector)
     2633         (macptr)))
     2634
     2635      (defmethod initialize-instance ((wrapper wrapper) &rest; initargs)
     2636        (declare (ignore initargs))
     2637        (call-next-method)
     2638        (ccl:terminate-when-unreachable wrapper)
     2639        (with-slots (ivector macptr element-type element-count) wrapper
     2640          (multiple-value-bind (new-ivector new-macptr)
     2641              (make-heap-ivector element-count element-type)
     2642            (setq ivector new-ivector
     2643                  macptr new-macptr))))
     2644
     2645      (defmethod ccl:terminate ((wrapper wrapper))
     2646        (with-slots (ivector macptr) wrapper
     2647          (when ivector
     2648            (dispose-heap-ivector ivector macptr)
     2649            (setq ivector nil
     2650                  macptr nil))))
     2651    </programlisting>
     2652    <para>The <literal>ccl:terminate</literal> method will be called
    26422653      on some arbitrary thread sometime (hopefully soon) after the GC
    26432654      has decided that there are no strong references to an object
    26442655      which has been the argument of a
    26452656      <literal>ccl:terminate-when-unreachable</literal> call.</para>
    2646       <para>If it makes sense to say that the foreign object should
     2657    <para>If it makes sense to say that the foreign object should
    26472658      live as long as there's Lisp code that references it (through
    26482659      the encapsulating obect) and no longer, this is one way of doing
    26492660      that.</para>
    2650       <para>Now we've covered passing basic types back and forth with
     2661    <para>Now we've covered passing basic types back and forth with
    26512662      C, and we've done the same with pointers.  You may think this is
    26522663      all...  but we've only done pointers to basic types.  Join us
    26532664      next time for pointers... to pointers.</para>
    26542665
    2655       <sect2 id="Acknowledgement--1-">
    2656         <title>Acknowledgement</title>
    2657         <para>Much of this chapter was generously contributed by
    2658         Andrew P. Lentvorski Jr.</para>
    2659       </sect2>
    2660     </sect1>
    2661 
    2662     <sect1>
    2663       <title>The Foreign-Function-Interface Dictionary</title>
     2666    <sect2 id="Acknowledgement--1-">
     2667          <title>Acknowledgement</title>
     2668          <para>Much of this chapter was generously contributed by
     2669            Andrew P. Lentvorski Jr.</para>
     2670    </sect2>
     2671  </sect1>
     2672
     2673  <!-- ******************************************  -->
     2674  <sect1>
     2675    <title>The Foreign-Function-Interface Dictionary</title>
     2676   
     2677    <!-- ====================================  -->
     2678    <refentry id="m_def-foreign-type">
     2679          <indexterm zone="m_def-foreign-type">
     2680            <primary>def-foreign-type</primary>
     2681          </indexterm>
     2682
     2683          <refnamediv>
     2684            <refname>DEF-FOREIGN-TYPE</refname>
     2685            <refpurpose></refpurpose>
     2686            <refclass>Macro</refclass>
     2687          </refnamediv>
     2688
     2689          <refsynopsisdiv>
     2690            <synopsis>
     2691              <function>def-foreign-type</function> name foreign-type-spec
     2692            </synopsis>
     2693          </refsynopsisdiv>
     2694
     2695          <refsect1>
     2696            <title>Values</title>
     2697
     2698            <variablelist>
     2699              <varlistentry>
     2700                <term>name</term>
     2701               
     2702                <listitem>
     2703                      <para>NIL or a keyword; the keyword may contain
     2704                        <link linkend="Case-sensitivity-of-foreign-names-in-CCL" >escaping constructs</link>.</para>
     2705                </listitem>
     2706              </varlistentry>
     2707             
     2708              <varlistentry>
     2709                <term>foreign-type-spec</term>
     2710               
     2711                <listitem>
     2712                      <para>A foreign type specifier, whose syntax is (loosely)
     2713                        defined above.</para>
     2714                </listitem>
     2715              </varlistentry>
     2716            </variablelist>
     2717          </refsect1>
     2718
     2719          <refsect1>
     2720            <title>Description</title>
     2721
     2722            <para>If name is non-NIL, defines name to be an alias for the
     2723              foreign type specified by foreign-type-spec. If foreign-type-spec
     2724              is a named structure or union type, additionally defines that
     2725              structure or union type.</para>
     2726           
     2727            <para>If name is NIL, foreign-type-spec must be a named foreign
     2728              struct or union definition, in which case the foreign structure
     2729              or
     2730              union definition is put in effect.</para>
     2731           
     2732            <para>Note that there are two separate namespaces for foreign
     2733              type names, one for the names of ordinary types and one for
     2734              the names of structs and unions.  Which one
     2735              <varname>name</varname> refers to depends on
     2736              <varname>foreign-type-spec</varname> in the obvious manner.
     2737            </para>
     2738          </refsect1>
     2739    </refentry>
     2740
     2741   
     2742    <!-- ====================================  -->
     2743    <refentry id="m_make-record">
     2744          <indexterm zone="m_make-record">
     2745            <primary>make-record</primary>
     2746          </indexterm>
     2747
     2748          <refnamediv>
     2749        <anchor id="anchor_make-record"/>
     2750            <refname>MAKE-RECORD</refname>
     2751            <refpurpose></refpurpose>
     2752            <refclass>Macro</refclass>
     2753          </refnamediv>
     2754
     2755          <refsynopsisdiv>
     2756            <synopsis>
     2757              <function>make-record</function> typespec
     2758              &rest; initforms => result
     2759            </synopsis>
     2760          </refsynopsisdiv>
     2761
     2762          <refsect1>
     2763            <title>Values</title>
     2764
     2765            <variablelist>
     2766              <varlistentry>
     2767                <term>typespec</term>
     2768
     2769                <listitem>
     2770                      <para>A foreign type specifier, or a keyword which is used
     2771                        as the name of a foreign struct or union.</para>
     2772                </listitem>
     2773              </varlistentry>
     2774
     2775              <varlistentry>
     2776                <term>initforms</term>
     2777
     2778                <listitem>
     2779                      <para>If the type denoted by <varname>typespec</varname>
     2780                        is scalar, a single value appropriate for that type;
     2781                        otherwise, a list of alternating field names and
     2782                        values appropriate for the types of those fields.</para>
     2783                </listitem>
     2784              </varlistentry>
     2785
     2786              <varlistentry>
     2787                <term>result</term>
     2788
     2789                <listitem>
     2790                      <para>
     2791                        A <type>macptr</type> which encapsulates the address of a
     2792                        newly-allocated record on the foreign heap.
     2793                      </para>
     2794                </listitem>
     2795              </varlistentry>
     2796            </variablelist>
     2797          </refsect1>
     2798
     2799          <refsect1>
     2800            <title>Description</title>
     2801
     2802            <para>
     2803              Expands into code which allocates and initalizes
     2804              an instance of the type
     2805              denoted by <varname>typespec</varname>, on the foreign
     2806              heap.  The record is allocated using the C function
     2807              <function>malloc</function>, and the user of
     2808              <function>make-record</function> must explicitly call
     2809              the C function <function>free</function> to deallocate the
     2810              record, when it is no longer needed.
     2811            </para>
     2812
     2813            <para>
     2814              If <varname>initforms</varname> is provided, its value
     2815              or values are used in the initialization.  When the type
     2816              is a scalar, <varname>initforms</varname> is either a single
     2817              value which can be coerced to that type, or no value, in which
     2818              case binary 0 is used.  When the type is a <type>struct</type>,
     2819              <varname>initforms</varname> is a list, giving field names
     2820              and the values for each.  Each field is treated in the same way
     2821              as a scalar is: If a value for it is given, it must be
     2822              coerceable to the field's type; if not, binary 0 is used.
     2823            </para>
     2824
     2825            <para>
     2826              When the type is an array, <varname>initforms</varname> may
     2827              not be provided, because <function>make-record</function>
     2828              cannot initialize its values.  <function>make-record</function>
     2829              is also unable to initialize fields of a <type>struct</type>
     2830              which are themselves
     2831              <type>struct</type>s.  The user of
     2832              <function>make-record</function> should set these values
     2833              by another means.
     2834            </para>
     2835
     2836            <para>
     2837              A possibly-significant limitation is that it must be possible to
     2838              find the foreign type at the time the macro is expanded;
     2839              <function>make-record</function> signals an error if this is
     2840              not the case.
     2841            </para>
     2842          </refsect1>
     2843
     2844          <refsect1>
     2845            <title>Notes</title>
     2846
     2847            <para>
     2848              It is inconvenient that <function>make-record</function> is a
     2849              macro, because this means that <varname>typespec</varname>
     2850              cannot be a variable; it must be an immediate value.
     2851            </para>
     2852           
     2853            <para>
     2854              If it weren't for this requirement,
     2855              <function>make-record</function> could be a function.  However,
     2856              that would mean that any stand-alone application using it would
     2857              have to include a copy of the interface database
     2858              (see <xref linkend="The-Interface-Database"/>), which is undesireable
     2859              because it's large.
     2860            </para>
     2861          </refsect1>
     2862    </refentry>
     2863
     2864    <!-- ====================================  -->
     2865    <refentry id="m_makegcable--record">
     2866      <indexterm zone="m_make-record">
     2867            <primary>make-gcable-record</primary>
     2868      </indexterm>
     2869
     2870      <refnamediv>
     2871            <refname>MAKE-GCABLE-RECORD</refname>
     2872            <refpurpose></refpurpose>
     2873            <refclass>Macro</refclass>
     2874      </refnamediv>
     2875
     2876      <refsynopsisdiv>
     2877            <synopsis>
     2878              <function>make-gcable-record</function> typespec
     2879              &rest; initforms => result
     2880            </synopsis>
     2881      </refsynopsisdiv>
     2882
     2883      <refsect1>
     2884            <title>Values</title>
     2885
     2886            <variablelist>
     2887              <varlistentry>
     2888                <term>typespec</term>
     2889
     2890                <listitem>
     2891                      <para>A foreign type specifier, or a keyword which is used
     2892                        as the name of a foreign struct or union.</para>
     2893                </listitem>
     2894              </varlistentry>
     2895
     2896              <varlistentry>
     2897                <term>initforms</term>
     2898
     2899                <listitem>
     2900                      <para>If the type denoted by <varname>typespec</varname>
     2901                        is scalar, a single value appropriate for that type;
     2902                        otherwise, a list of alternating field names and
     2903                        values appropriate for the types of those fields.</para>
     2904                </listitem>
     2905              </varlistentry>
     2906
     2907              <varlistentry>
     2908                <term>result</term>
     2909
     2910                <listitem>
     2911                      <para>
     2912                        A <type>macptr</type> which encapsulates the address of a
     2913                        newly-allocated record on the foreign heap. The foreign
     2914                        object returned by <function>make-gcable-record</function>
     2915                        is freed when the garbage collector determines that
     2916                        the <code>MACPTR</code> object that describes it is
     2917                        unreachable.</para>
     2918                </listitem>
     2919              </varlistentry>
     2920            </variablelist>
     2921      </refsect1>
     2922
     2923      <refsect1>
     2924            <title>Description</title>
     2925
     2926            <para>
     2927              Allocates a block of foreign memory suitable to hold the foreign
     2928              type described by <code>typespec</code>, in the same manner
     2929              as <link linkend="anchor_make-record">MAKE-RECORD</link>. In
     2930              addition, <code>MAKE-GCABLE-RECORD</code> marks the
     2931              returned object gcable; in other words, it informs the garbage
     2932              collector that it may reclaim the object when it becomes
     2933              unreachable.
     2934            </para>
     2935
     2936        <para>In all other respects, <code>MAKE-GCABLE-RECORD</code> works
     2937          the same way
     2938          as <link linkend="anchor_make-record">MAKE-RECORD</link></para>
     2939
     2940        <para> When using gcable pointers, it's important to remember the
     2941          distinction between a <code>MACPTR</code> object (which is a
     2942          lisp object, more or less like any other) and the block of
     2943          foreign memory that the <code>MACPTR</code> object points to.
     2944          If a gcable <code>MACPTR</code> object is the only thing in the
     2945          world (lisp world or foreign world) that references the
     2946          underlying block of foreign memory, then freeing the foreign
     2947          memory when it becomes impossible to reference it is convenient
     2948          and sane.  If other lisp <code>MACPTR</code>s reference the
     2949          underlying block of foreign memory or if the address of that
     2950          foreign memory is passed to and retained by foreign code, having
     2951          the GC free the memory may have unpleasant consequences if those
     2952          other references are used.</para>
     2953
     2954        <para>Take care, therefore, not to create a gcable record unless
     2955          you are sure that the returned <code>MACPTR</code> will be the
     2956          only reference to the allocated memory that will ever be
     2957          used.</para>
     2958      </refsect1>
     2959
     2960    </refentry>
     2961
     2962
     2963
     2964    <!-- ====================================  -->
     2965    <refentry id="m_rlet">
     2966          <indexterm zone="m_rlet">
     2967            <primary>rlet</primary>
     2968          </indexterm>
     2969
     2970          <refnamediv>
     2971            <refname>RLET</refname>
     2972            <refpurpose></refpurpose>
     2973            <refclass>Macro</refclass>
     2974          </refnamediv>
     2975
     2976          <refsynopsisdiv>
     2977            <synopsis>
     2978              <function>rlet</function> (var typespec &rest; initforms)*
     2979              &body; body
     2980            </synopsis>
     2981          </refsynopsisdiv>
     2982
     2983          <refsect1>
     2984            <title>Values</title>
     2985
     2986            <variablelist>
     2987              <varlistentry>
     2988                <term>var</term>
     2989
     2990                <listitem>
     2991                      <para>A symbol (a lisp variable)</para>
     2992                </listitem>
     2993              </varlistentry>
     2994
     2995              <varlistentry>
     2996                <term>typespec</term>
     2997
     2998                <listitem>
     2999                      <para>A foreign type specifier or foreign record name.</para>
     3000                </listitem>
     3001              </varlistentry>
     3002
     3003          <varlistentry>
     3004                <term>initforms</term>
     3005
     3006                <listitem>
     3007                      <para>As described above, for
     3008                        <xref linkend="m_make-record"/></para>
     3009                </listitem>
     3010              </varlistentry>
     3011            </variablelist>
     3012          </refsect1>
     3013
     3014          <refsect1>
     3015            <title>Description</title>
     3016
     3017            <para>Executes <varname>body</varname>
     3018              in an environment in which each var is bound
     3019              to <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link> encapsulating the
     3020              address of a stack-allocated foreign memory block, allocated and
     3021              initialized from typespec and initforms as per
     3022              <xref linkend="m_make-record"/>.
     3023              Returns whatever value(s) <varname>body</varname>
     3024              returns.</para>
     3025           
     3026            <para>Record fields that aren&#39;t explicitly initialized have
     3027              unspecified contents.</para>
     3028          </refsect1>
     3029    </refentry>
     3030
     3031    <!-- ====================================  -->
     3032    <refentry id="m_rletz">
     3033          <indexterm zone="m_rletz">
     3034            <primary>rletz</primary>
     3035          </indexterm>
     3036
     3037          <refnamediv>
     3038            <refname>RLETZ</refname>
     3039            <refpurpose></refpurpose>
     3040            <refclass>Macro</refclass>
     3041          </refnamediv>
     3042
     3043          <refsynopsisdiv>
     3044            <synopsis>
     3045              <function>rletz</function> (var typespec &rest; initforms)*
     3046              &body; body
     3047            </synopsis>
     3048          </refsynopsisdiv>
     3049
     3050          <refsect1>
     3051            <title>Values</title>
     3052
     3053            <variablelist>
     3054              <varlistentry>
     3055                <term>var</term>
     3056
     3057                <listitem>
     3058                      <para>A symbol (a lisp variable)</para>
     3059                </listitem>
     3060              </varlistentry>
     3061
     3062              <varlistentry>
     3063                <term>typespec</term>
     3064
     3065                <listitem>
     3066                      <para>A foreign type specifier or foreign record name.</para>
     3067                </listitem>
     3068              </varlistentry>
     3069
     3070              <varlistentry>
     3071                <term>initforms</term>
     3072
     3073                <listitem>
     3074                      <para>As described above, for ccl:make-record</para>
     3075                </listitem>
     3076              </varlistentry>
     3077            </variablelist>
     3078          </refsect1>
     3079
     3080          <refsect1>
     3081            <title>Description</title>
     3082
     3083            <para>Executes body in an environment in which each var is
     3084              bound to <link
     3085                          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
     3086                MACPTR</link> encapuslating the address of a stack-allocated
     3087              foreign memory block, allocated and initialized from
     3088              typespec and initforms as ccl:make-record.</para>
     3089           
     3090            <para>Returns whatever value(s) body returns.</para>
     3091
     3092            <para>Unlike rlet, record fields that aren&#39;t explicitly
     3093              initialized are set to binary 0.</para>
     3094          </refsect1>
     3095    </refentry>
     3096
     3097    <!-- ====================================  -->
     3098    <refentry id="m_pref">
     3099          <indexterm zone="m_pref">
     3100            <primary>pref</primary>
     3101          </indexterm>
     3102
     3103          <refnamediv>
     3104            <refname>PREF</refname>
     3105            <refpurpose></refpurpose>
     3106            <refclass>Macro</refclass>
     3107          </refnamediv>
     3108
     3109          <refsynopsisdiv>
     3110            <synopsis>
     3111              <function>pref</function> ptr accessor-form
     3112            </synopsis>
     3113
     3114          </refsynopsisdiv>
     3115
     3116          <refsect1>
     3117            <title>Values</title>
     3118
     3119            <variablelist>
     3120              <varlistentry>
     3121                <term>ptr</term>
     3122
     3123                <listitem>
     3124                      <para><link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
     3125                </listitem>
     3126              </varlistentry>
     3127
     3128              <varlistentry>
     3129                <term>accessor-form</term>
     3130
     3131                <listitem>
     3132                      <para>a keyword which names a foreign type or record, as
     3133                        described in <xref linkend="Foreign-type--record--and-field-names"/>.
     3134                      </para>
     3135                </listitem>
     3136              </varlistentry>
     3137            </variablelist>
     3138          </refsect1>
     3139
     3140          <refsect1>
     3141            <title>Description</title>
     3142
     3143            <para>References an instance of a foreign type (or a component of
     3144              a foreign type) accessible via ptr.</para>
     3145           
     3146            <para>Expands into code which references the indicated scalar type
     3147              or component, or returns a pointer to a composite type.</para>
     3148           
     3149            <para>PREF can be used with SETF.</para>
     3150           
     3151            <para>RREF is a deprecated alternative to PREF. It accepts a
     3152              :STORAGE keyword and rather loudly ignores it.</para>
     3153          </refsect1>
     3154    </refentry>
     3155
     3156    <!-- ====================================  -->
     3157    <refentry id="f_open-shared-library">
     3158          <indexterm zone="f_open-shared-library">
     3159            <primary>open-shared-library</primary>
     3160          </indexterm>
     3161         
     3162          <refnamediv>
     3163            <refname>OPEN-SHARED-LIBRARY</refname>
     3164            <refpurpose>Asks the operating system to load a shared library
     3165              for &CCL; to use.</refpurpose>
     3166            <refclass>Function</refclass>
     3167          </refnamediv>
     3168         
     3169          <refsynopsisdiv>
     3170            <synopsis>
     3171              <function>open-shared-library</function> name => library
     3172            </synopsis>
     3173          </refsynopsisdiv>
     3174         
     3175          <refsect1>
     3176            <title>Values</title>
     3177           
     3178            <variablelist>
     3179              <varlistentry>
     3180                <term>name</term>       
     3181                <listitem>
     3182                      <para>A SIMPLE-STRING which is presumed to be the so-name of
     3183                        or a filesystem path to the library.</para>
     3184                </listitem>
     3185              </varlistentry>
     3186             
     3187              <varlistentry>
     3188                <term>library</term>
     3189                <listitem>
     3190                      <para>An object of type SHLIB which describes the
     3191                        library denoted by <varname>name</varname>.</para>
     3192                </listitem>
     3193              </varlistentry>
     3194            </variablelist>
     3195          </refsect1>
     3196         
     3197          <refsect1>
     3198            <title>Description</title>
     3199
     3200            <para>If the library denoted by <varname>name</varname> can
     3201              be loaded by the
     3202              operating system, returns an object of type SHLIB that describes
     3203              the library; if the library is already open, increments a
     3204              reference count. If the library can&#39;t be loaded, signals a
     3205              SIMPLE-ERROR which contains an often-cryptic message from the
     3206              operating system.</para>
     3207          </refsect1>
     3208
     3209          <refsect1>
     3210            <title>Examples</title>
     3211
     3212            <programlisting format="linespecific">;;; Try to do something simple.
     3213          ? (open-shared-library &#34;libgtk.so&#34;)
     3214          &#62; Error: Error opening shared library &#34;libgtk.so&#34;: /usr/lib/libgtk.so: undefined symbol: gdk_threads_mutex
     3215          &#62; While executing: OPEN-SHARED-LIBRARY
     3216
     3217          ;;; Grovel around, curse, and try to find out where &#34;gdk_threads_mutex&#34;
     3218          ;;; might be defined. Then try again:
     3219
     3220          ? (open-shared-library &#34;libgdk.so&#34;)
     3221          #&#60;SHLIB libgdk.so #x3046DBB6&#62;
     3222
     3223          ? (open-shared-library &#34;libgtk.so&#34;)
     3224          #&#60;SHLIB libgtk.so #x3046DC86&#62;
     3225
     3226          ;;; Reference an external symbol defined in one of those libraries.
     3227
     3228          ? (external &#34;gtk_main&#34;)
     3229          #&#60;EXTERNAL-ENTRY-POINT &#34;gtk_main&#34; (#x012C3004) libgtk.so #x3046FE46&#62;
     3230
     3231          ;;; Close those libraries.
     3232
     3233          ? (close-shared-library &#34;libgtk.so&#34;)
     3234          T
     3235
     3236          ? (close-shared-library &#34;libgdk.so&#34;)
     3237          T
     3238
     3239          ;;; Reference the external symbol again.
     3240
     3241          ? (external &#34;gtk_main&#34;)
     3242          #&#60;EXTERNAL-ENTRY-POINT &#34;gtk_main&#34; {unresolved} libgtk.so #x3046FE46&#62;</programlisting>
     3243          </refsect1>
     3244
     3245          <refsect1>
     3246            <title>Notes</title>
     3247
     3248            <para>It would be helpful to describe what an soname is and give
     3249              examples of one.</para>
     3250
     3251            <para>Does the SHLIB still get returned if the library is
     3252              already open?</para>
     3253          </refsect1>
     3254    </refentry>
     3255
     3256    <!-- ====================================  -->
     3257    <refentry id="f_close-shared-library">
     3258          <indexterm zone="f_close-shared-library">
     3259            <primary>close-shared-library</primary>
     3260          </indexterm>
     3261
     3262          <refnamediv>
     3263            <refname>CLOSE-SHARED-LIBRARY</refname>
     3264            <refpurpose>Stops using a shared library, informing the operating
     3265              system that it can be unloaded if appropriate.</refpurpose>
     3266            <refclass>Function</refclass>
     3267          </refnamediv>
     3268
     3269          <refsynopsisdiv>
     3270            <synopsis>
     3271              <function>close-shared-library</function> library &key;
     3272              completely</synopsis>
     3273          </refsynopsisdiv>
     3274
     3275          <refsect1>
     3276            <title>Values</title>
     3277
     3278            <variablelist>
     3279              <varlistentry>
     3280                <term>library</term>
     3281
     3282                <listitem>
     3283                      <para>either an object of type SHLIB, or a string which
     3284                        designates one by its so-name.</para>
     3285                </listitem>
     3286              </varlistentry>
     3287
     3288              <varlistentry>
     3289                <term>completely</term>
     3290
     3291                <listitem>
     3292                      <para>a boolean.  The default is T.</para>
     3293                </listitem>
     3294              </varlistentry>
     3295            </variablelist>
     3296          </refsect1>
     3297
     3298          <refsect1>
     3299            <title>Description</title>
     3300
     3301            <para>If <varname>completely</varname> is T, sets the
     3302              reference count of <varname>library</varname> to 0.  Otherwise,
     3303              decrements it by 1.  In either case, if the reference count
     3304              becomes 0, <function>close-shared-library</function>
     3305              frees all memory resources consumed <varname>library</varname>
     3306              and
     3307              causes any EXTERNAL-ENTRY-POINTs known to be defined by it to
     3308              become unresolved.</para>
     3309          </refsect1>
     3310    </refentry>
     3311
     3312    <!-- ====================================  -->
     3313    <refentry id="m_external">
     3314          <indexterm zone="m_external">
     3315            <primary>external</primary>
     3316          </indexterm>
     3317         
     3318          <refnamediv>
     3319            <refname>EXTERNAL</refname>
     3320            <refpurpose>Resolves a reference to an external symbol which
     3321              is defined in a shared library.</refpurpose>
     3322            <refclass>Macro</refclass>
     3323          </refnamediv>
     3324
     3325          <refsynopsisdiv>
     3326            <synopsis>
     3327              <function>external</function> name => entry
     3328            </synopsis>
     3329          </refsynopsisdiv>
     3330
     3331          <refsect1>
     3332            <title>Values</title>
     3333
     3334            <variablelist>
     3335              <varlistentry>
     3336                <term>name</term>
     3337                <listitem>
     3338                      <para>
     3339                        a simple-string which names an external symbol.
     3340                        Case-sensitive.
     3341                      </para>
     3342                </listitem>
     3343              </varlistentry>
     3344              <varlistentry>
     3345                <term>entry</term>
     3346                <listitem>
     3347                      <para>
     3348                        an object of type EXTERNAL-ENTRY-POINT which maintains
     3349                        the address of the foreign symbol named by
     3350                        <varname>name</varname>.
     3351                      </para>
     3352                </listitem>
     3353              </varlistentry>
     3354            </variablelist>
     3355          </refsect1>
     3356
     3357          <refsect1>
     3358            <title>Description</title>
     3359
     3360            <para>If there is already an EXTERNAL-ENTRY-POINT for
     3361              the symbol named by <varname>name</varname>, finds it and
     3362              returns it.  If not, creates one and returns it.</para>
     3363
     3364            <para>Tries to resolve the entry point to a memory address,
     3365              and identify the containing library.</para>
     3366
     3367            <para>Be aware that under Darwin, external functions which
     3368              are callable from C have underscores prepended to their names,
     3369              as in "_fopen".</para>
     3370          </refsect1>
     3371    </refentry>
     3372
     3373    <!-- ====================================  -->
     3374    <refentry id="f_Pff-call">
     3375          <indexterm zone="f_Pff-call">
     3376            <primary>%ff-call</primary>
     3377          </indexterm>
     3378
     3379          <refnamediv>
     3380            <refname>%FF-CALL</refname>
     3381            <refpurpose></refpurpose>
     3382            <refclass>Function</refclass>
     3383          </refnamediv>
     3384
     3385          <refsynopsisdiv>
     3386            <synopsis>
     3387              <function>%ff-call</function> entrypoint
     3388              {arg-type-keyword arg}* &optional; result-type-keyword
     3389            </synopsis>
     3390          </refsynopsisdiv>
     3391
     3392          <refsect1>
     3393            <title>Values</title>
     3394
     3395            <variablelist>
     3396              <varlistentry>
     3397                <term>entrypoint</term>
     3398               
     3399                <listitem>
     3400                      <para>A fixnum or MACPTR</para>
     3401                </listitem>
     3402              </varlistentry>
     3403
     3404              <varlistentry>
     3405                <term>arg-type-keyword</term>
     3406
     3407                <listitem>
     3408                      <para>One of the foreign argument-type keywords, described
     3409                        above</para>
     3410                </listitem>
     3411              </varlistentry>
     3412
     3413              <varlistentry>
     3414                <term>arg</term>
     3415
     3416                <listitem>
     3417                      <para>A lisp value of type indicated by the corresponding
     3418                        arg-type-keyword</para>
     3419                </listitem>
     3420              </varlistentry>
     3421
     3422              <varlistentry>
     3423                <term>result-type-keyword</term>
     3424
     3425                <listitem>
     3426                      <para>One of the foreign argument-type keywords, described
     3427                        above</para>
     3428                </listitem>
     3429              </varlistentry>
     3430            </variablelist>
     3431          </refsect1>
     3432
     3433          <refsect1>
     3434            <title>Description</title>
     3435
     3436            <para>Calls the foreign function at address entrypoint passing the
     3437              values of each arg as a foreign argument of type indicated by the
     3438              corresponding arg-type-keyword. Returns the foreign function
     3439              result (coerced to a Lisp object of type indicated by
     3440              result-type-keyword), or NIL if result-type-keyword is :VOID or
     3441              NIL</para>
     3442          </refsect1>
     3443    </refentry>
     3444
     3445    <!-- ====================================  -->
     3446    <refentry id="m_ff-call">
     3447          <indexterm zone="m_ff-call">
     3448            <primary>ff-call</primary>
     3449          </indexterm>
     3450
     3451          <refnamediv>
     3452            <refname>FF-CALL</refname>
     3453            <refpurpose></refpurpose>
     3454            <refclass>Macro</refclass>
     3455          </refnamediv>
     3456
     3457          <refsynopsisdiv>
     3458            <synopsis>
     3459              <function>ff-call</function> entrypoint
     3460              {arg-type-specifier arg}* &optional; result-type-specifier
     3461            </synopsis>
     3462          </refsynopsisdiv>
     3463
     3464          <refsect1>
     3465            <title>Values</title>
     3466
     3467            <variablelist>
     3468              <varlistentry>
     3469                <term>entrypoint</term>
     3470
     3471                <listitem>
     3472                      <para>A fixnum or MACPTR</para>
     3473                </listitem>
     3474              </varlistentry>
     3475
     3476              <varlistentry>
     3477                <term>arg-type-specifer</term>
     3478
     3479                <listitem>
     3480                      <para>One of the foreign argument-type keywords, described
     3481                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3482                          type specifier</link>.</para>
     3483                </listitem>
     3484              </varlistentry>
     3485
     3486              <varlistentry>
     3487                <term>arg</term>
     3488
     3489                <listitem>
     3490                      <para>A lisp value of type indicated by the corresponding
     3491                        arg-type-specifier</para>
     3492                </listitem>
     3493              </varlistentry>
     3494
     3495              <varlistentry>
     3496                <term>result-type-specifier</term>
     3497
     3498                <listitem>
     3499                      <para>One of the foreign argument-type keywords, described
     3500                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3501                          type specifier</link>.</para>
     3502                </listitem>
     3503              </varlistentry>
     3504            </variablelist>
     3505          </refsect1>
     3506
     3507          <refsect1>
     3508            <title>Description</title>
     3509
     3510            <para>Calls the foreign function at address entrypoint passing the
     3511              values of each arg as a foreign argument of type indicated by the
     3512              corresponding arg-type-specifier. Returns the foreign function
     3513              result (coerced to a Lisp object of type indicated by
     3514              result-type-specifier), or NIL if result-type-specifer is :VOID or
     3515              NIL</para>
     3516          </refsect1>
     3517    </refentry>
     3518
     3519    <!-- ====================================  -->
     3520    <refentry id="f_Preference-external-entry-point">
     3521          <indexterm zone="f_Preference-external-entry-point">
     3522            <primary>%reference-external-entry-point</primary>
     3523          </indexterm>
     3524
     3525          <refnamediv>
     3526            <refname>%REFERENCE-EXTERNAL-ENTRY-POINT</refname>
     3527            <refpurpose></refpurpose>
     3528            <refclass>Function</refclass>
     3529          </refnamediv>
     3530
     3531          <refsynopsisdiv>
     3532            <synopsis>
     3533              <function>%reference-external-entry-point</function> eep
     3534            </synopsis>
     3535          </refsynopsisdiv>
     3536
     3537          <refsect1>
     3538            <title>Values</title>
     3539
     3540            <variablelist>
     3541              <varlistentry>
     3542                <term>eep</term>
     3543
     3544                <listitem>
     3545                      <para>An EXTERNAL-ENTRY-POINT, as obtained by the EXTERNAL
     3546                        macro.</para>
     3547                </listitem>
     3548              </varlistentry>
     3549            </variablelist>
     3550          </refsect1>
     3551
     3552          <refsect1>
     3553            <title>Description</title>
     3554
     3555            <para>Tries to resolve the address of the EXTERNAL-ENTRY-POINT
     3556              eep; returns a fixnum representation of that address if
     3557              successful, else signals an error.</para>
     3558          </refsect1>
     3559    </refentry>
     3560
     3561    <!-- ====================================  -->
     3562    <refentry id="m_external-call">
     3563          <indexterm zone="m_external-call">
     3564            <primary>external-call</primary>
     3565          </indexterm>
     3566
     3567          <refnamediv>
     3568            <refname>EXTERNAL-CALL</refname>
     3569            <refpurpose></refpurpose>
     3570            <refclass>Macro</refclass>
     3571          </refnamediv>
     3572
     3573          <refsynopsisdiv>
     3574            <synopsis>
     3575              <function>external-call</function> name
     3576              {arg-type-specifier arg}* &optional; result-type-specifier
     3577            </synopsis>
     3578          </refsynopsisdiv>
     3579
     3580          <refsect1>
     3581            <title>Values</title>
     3582
     3583            <variablelist>
     3584              <varlistentry>
     3585                <term>name</term>
     3586
     3587                <listitem>
     3588                      <para>A lisp string. See external, above.</para>
     3589                </listitem>
     3590              </varlistentry>
     3591
     3592              <varlistentry>
     3593                <term>arg-type-specifer</term>
     3594
     3595                <listitem>
     3596                      <para>One of the foreign argument-type keywords, described
     3597                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3598                          type specifier</link>.</para>
     3599                </listitem>
     3600              </varlistentry>
     3601
     3602              <varlistentry>
     3603                <term>arg</term>
     3604
     3605                <listitem>
     3606                      <para>A lisp value of type indicated by the corresponding
     3607                        arg-type-specifier</para>
     3608                </listitem>
     3609              </varlistentry>
     3610
     3611              <varlistentry>
     3612                <term>result-type-specifier</term>
     3613
     3614                <listitem>
     3615                      <para>One of the foreign argument-type keywords, described
     3616                        above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
     3617                          type specifier</link>.</para>
     3618                </listitem>
     3619              </varlistentry>
     3620            </variablelist>
     3621          </refsect1>
     3622
     3623          <refsect1>
     3624            <title>Description</title>
     3625
     3626            <para>Calls the foreign function at the address obtained by
     3627              resolving the external-entry-point associated with name, passing
     3628              the values of each arg as a foreign argument of type indicated by
     3629              the corresponding arg-type-specifier. Returns the foreign function
     3630              result (coerced to a Lisp object of type indicated by
     3631              result-type-specifier), or NIL if result-type-specifer is :VOID or
     3632              NIL</para>
     3633          </refsect1>
     3634    </refentry>
     3635
     3636    <!-- ====================================  -->
     3637    <refentry id="f_foreign-symbol-entry">
     3638          <indexterm zone="f_foreign-symbol-entry">
     3639            <primary>foreign-symbol-entry</primary>
     3640          </indexterm>
     3641
     3642          <refnamediv>
     3643            <refname>FOREIGN-SYMBOL-ENTRY</refname>
     3644            <refpurpose></refpurpose>
     3645            <refclass>Function</refclass>
     3646          </refnamediv>
     3647
     3648          <refsynopsisdiv>
     3649            <synopsis>
     3650              <function>foreign-symbol-entry</function> name
     3651            </synopsis>
     3652          </refsynopsisdiv>
     3653
     3654          <refsect1>
     3655            <title>Values</title>
     3656
     3657            <variablelist>
     3658              <varlistentry>
     3659                <term>name</term>
     3660
     3661                <listitem>
     3662                      <para>A lisp string.</para>
     3663                </listitem>
     3664              </varlistentry>
     3665            </variablelist>
     3666          </refsect1>
     3667
     3668          <refsect1>
     3669            <title>Description</title>
     3670
     3671            <para>Tries to resolve the address of the foreign symbol name. If
     3672              successful, returns a fixnum representation of that address, else
     3673              returns NIL.</para>
     3674          </refsect1>
     3675    </refentry>
     3676
     3677    <!-- ====================================  -->
     3678    <refentry id="f_foreign-symbol-address">
     3679          <indexterm zone="f_foreign-symbol-address">
     3680            <primary>foreign-symbol-address</primary>
     3681          </indexterm>
     3682
     3683          <refnamediv>
     3684            <refname>FOREIGN-SYMBOL-ADDRESS</refname>
     3685            <refpurpose></refpurpose>
     3686            <refclass>Function</refclass>
     3687          </refnamediv>
     3688
     3689          <refsynopsisdiv>
     3690            <synopsis>
     3691              <function>foreign-symbol-address</function> name
     3692            </synopsis>
     3693          </refsynopsisdiv>
     3694
     3695          <refsect1>
     3696            <title>Values</title>
     3697
     3698            <variablelist>
     3699              <varlistentry>
     3700                <term>name</term>
     3701
     3702                <listitem>
     3703                      <para>A lisp string.</para>
     3704                </listitem>
     3705              </varlistentry>
     3706            </variablelist>
     3707          </refsect1>
     3708
     3709          <refsect1>
     3710            <title>Description</title>
     3711
     3712            <para>Tries to resolve the address of the foreign symbol
     3713              name. If successful, returns that address encapsulated in
     3714              <link
     3715                 linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
     3716                MACPTR</link>, else returns NIL.</para>
     3717          </refsect1>
     3718    </refentry>
     3719
     3720    <!-- ====================================  -->
     3721    <refentry id="m_defcallback">
     3722          <indexterm zone="m_defcallback">
     3723            <primary>defcallback</primary>
     3724          </indexterm>
     3725
     3726          <refnamediv>
     3727            <refname>DEFCALLBACK</refname>
     3728            <refpurpose></refpurpose>
     3729            <refclass>Macro</refclass>
     3730          </refnamediv>
     3731
     3732          <refsynopsisdiv>
     3733            <synopsis>
     3734              <function>defcallback</function> name
     3735              ({arg-type-specifier var}* &optional; result-type-specifier)
     3736              &body; body
     3737            </synopsis>
     3738          </refsynopsisdiv>
     3739
     3740          <refsect1>
     3741            <title>Values</title>
     3742
     3743            <variablelist>
     3744              <varlistentry>
     3745                <term>name</term>
     3746
     3747                <listitem>
     3748                      <para>A symbol which can be made into a special variable</para>
     3749                </listitem>
     3750              </varlistentry>
     3751
     3752              <varlistentry>
     3753                <term>arg-type-specifer</term>
     3754
     3755                <listitem>
     3756                      <para>One of the foreign argument-type keywords,
     3757                        described above, or an equivalent <link
     3758                                                             linkend="Specifying-And-Using-Foreign-Types">foreign
     3759                          type specifier</link>.  In addition, if the keyword
     3760                        :WITHOUT-INTERRUPTS is specified, the callback will be
     3761                        executed with lisp interrupts disabled if the
     3762                        corresponding var is non-NIL. If :WITHOUT-INTERRUPTS
     3763                        is specified more than once, the rightmost instance
     3764                        wins.</para>
     3765                </listitem>
     3766              </varlistentry>
     3767
     3768              <varlistentry>
     3769                <term>var</term>
     3770
     3771                <listitem>
     3772                      <para>A symbol (lisp variable), which will be bound to a
     3773                        value of the specified type.</para>
     3774                </listitem>
     3775              </varlistentry>
     3776
     3777              <varlistentry>
     3778                <term>body</term>
     3779
     3780                <listitem>
     3781                      <para>A sequence of lisp forms, which should return a value
     3782                        which can be coerced to the specified result-type.</para>
     3783                </listitem>
     3784              </varlistentry>
     3785            </variablelist>
     3786          </refsect1>
     3787
     3788          <refsect1>
     3789            <title>Description</title>
     3790
     3791            <para>Proclaims <varname>name</varname>
     3792              to be a special variable; sets its value to a
     3793              MACPTR which, when called by foreign code, calls a lisp function
     3794              which expects foreign arguments of the specified types and which
     3795              returns a foreign value of the specified result type. Any argument
     3796              variables which correspond to foreign arguments of type :ADDRESS
     3797              are bound to stack-allocated MACPTRs.</para>
     3798           
     3799            <para>If <varname>name</varname>
     3800              is already a callback function pointer, its value is
     3801              not changed; instead, it&#39;s arranged
     3802              that an
     3803              updated version of the lisp callback function will be called.
     3804              This feature allows for callback functions to be redefined
     3805              incrementally, just like Lisp functions are.</para>
     3806
     3807            <para><function>defcallback</function>
     3808              returns the callback pointer, e.g., the
     3809              value of <varname>name</varname>.</para>
     3810          </refsect1>
     3811    </refentry>
     3812
     3813
     3814    <!-- ====================================  -->
     3815    <refentry id="rm_sharpsign-underscore">
     3816      <indexterm zone="rm_sharpsign-underscore">
     3817            <primary>#_</primary>
     3818      </indexterm>
     3819
     3820      <refnamediv>
     3821            <refname>#_</refname>
     3822            <refpurpose></refpurpose>
     3823            <refclass>Reader Macro</refclass>
     3824      </refnamediv>
     3825
     3826      <refsect1>
     3827            <title>Description</title>
     3828
     3829            <para>Reads a symbol from the current input stream, with *PACKAGE*
     3830              bound to the &#34;OS&#34; package and with readtable-case preserved.</para>