source: trunk/source/doc/src/ffi.xml @ 8606

Last change on this file since 8606 was 8606, checked in by gb, 13 years ago

Rename chapter-level files to not include chapter numbers (so that it'd be
less confusing to change chapter order, remove/introduce chapters, etc.)

Ensure that all chapter-level files have ENTITY definitions in their
DOCTYPE forms.

Define a CCL entity (currently just <literal>CCL</literal>; change all
references to "OpenMCL" to "&CCL;"

File size: 126.9 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!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]>
11
12  <chapter id="The-Foreign-Function-Interface">
13    <title>The Foreign-Function Interface</title>
14
15    <sect1 id="Specifying-And-Using-Foreign-Types">
16      <title>Specifying And Using Foreign Types</title>
17
18      <sect2 id="Overview-foreign-types">
19        <title>Overview</title>
20        <para>&CCL; provides a fairly rich language for defining and
21        specifying foreign data types (this language is derived from
22        CMUCL's "alien type" system.)</para>
23        <para>In practice, most foreign type definitions are
24        introduced into &CCL; via its interface database (see ),
25        though it's also possible to define foreign types
26        interactively and/or programmatically.</para>
27        <para>&CCL;'s foreign type system is "evolving" (a polite
28        word for not-quite-complete): there are some inconsistencies
29        involving package usage, for instance. Symbols used in foreign
30        type specifiers <emphasis>should</emphasis> be keywords, but
31        this convention isn't always enforced.</para>
32        <para>Foreign type, record, and field names are
33        case-sensitive; &CCL; uses some escaping conventions (see )
34        to allow keywords to be used to denote these names.</para>
35      </sect2>
36
37      <sect2 id="Syntax-of-Foreign-Type-Specifiers">
38        <title>Syntax of Foreign Type Specifiers</title>
39        <itemizedlist>
40          <listitem>
41            <para>Some foreign types are builtin: keywords denote
42            primitive,builtin types such as the IEEE-double-float type
43            (denoted:DOUBLE-FLOAT), in much the same way as certain
44            symbols(CONS, FIXNUM,etc.) define primitive CL
45            types.</para>
46          </listitem>
47          <listitem>
48            <para>Constructors such as :SIGNED and :UNSIGNED can be
49            used to denotesigned and unsigned integer subtypes
50            (analogous to the CL typespecifiers SIGNED-BYTE and
51            UNSIGNED-BYTE.) :SIGNED is shorthand for(:SIGNED 32) and
52            :UNSIGNED is shorthand for (:UNSIGNED 32).</para>
53          </listitem>
54          <listitem>
55            <para>Aliases for other (perhaps more complicated) types
56            can bedefined via CCL:DEF-FOREIGN-TYPE (sort of like
57            CL:DEFTYPE or the Ctypedef facility). The type :CHAR is
58            defined as an alias for (:SIGNED8) on some platforms, as
59            (:UNSIGNED 8) on others.</para>
60          </listitem>
61          <listitem>
62            <para>The construct (:STRUCT <emphasis>name</emphasis>)
63            can be used torefer to a named structure type; (:UNION
64            <emphasis>name</emphasis>)can be used to refer to a named
65            union type. It isn't necessary toenumerate a structure or
66            union type's fields in order to refer tothe type.</para>
67          </listitem>
68          <listitem>
69            <para>If <emphasis>X</emphasis> is a valid foreign type
70            reference,then (:* <emphasis>X</emphasis>) denotes the
71            foreign type "pointerto<emphasis> X</emphasis>". By
72            convention, (:* T) denotes ananonymous pointer type,
73            vaguely equivalent to "void*" in C.</para>
74          </listitem>
75          <listitem>
76            <para>If a fieldlist is a list of lists, each of whose CAR
77            is a foreign field name (keyword) and whose CADR is a
78            foreign type specifier, then (:STRUCT
79            <emphasis>name</emphasis> ,@fieldlist) is adefinition of
80            the structure type <emphasis>name</emphasis>,
81            and (:UNION<emphasis> name</emphasis> ,@fieldlist) is a
82            definition of theunion type
83            <emphasis>name</emphasis>. Note that it's necessary
84            todefine a structure or union type in order to include
85            that type in a structure, union, or array, but only
86            necessary to "refer to" a strucure or union type in order
87            to define a type alias or a pointer type.</para>
88          </listitem>
89          <listitem>
90            <para>If <emphasis>X</emphasis> is a defined foreign type
91            , then (:array <emphasis>X</emphasis> &amp;rest dims)
92            denotes the foreigntype "array of
93            <emphasis>X</emphasis>". Although multiplearray dimensions
94            are allowed by the :array constructor,
95            only single-dimensioned arrays are (at all) well-supported
96            in &CCL;.</para>
97          </listitem>
98        </itemizedlist>
99      </sect2>
100    </sect1>
101
102    <sect1 id="Foreign-Function-Calls">
103      <title>Foreign Function Calls</title>
104
105      <sect2 id="Overview-foreign-calls">
106        <title>Overview</title>
107        <para>&CCL; provides a number of constructs for calling
108        foreign functions from Lisp code (all of them based on the
109        function CCL:%FF-CALL).  In many cases, &CCL;'s interface
110        translator (see ) provides information about the foreign
111        function's entrypoint name and argument and return types; this
112        enables the use of the #_ reader macro (described below),
113        which may be more concise and/or more readable than other
114        constructs.</para>
115        <para>&CCL; also provides a mechanism for defining
116        <emphasis>callbacks</emphasis>: lisp functions which can be
117        called from foreign code.</para>
118        <para>There's no supported way to directly pass lisp data to
119        foreign functions: scalar lisp data must be coerced to an
120        equivalent foreign representatation, and lisp arrays (notably
121        strings) must be copied to non-GCed memory.</para>
122
123        <sect3 id="Type-Designators-for-Arguments-and-Return-Values">
124          <title>Type Designators for Arguments and Return Values</title>
125          <para>The types of foreign argument and return values in foreign
126          function calls and callbacks can be specified by any of the following
127keywords:</para>
128          <variablelist>
129            <varlistentry>
130              <term>:UNSIGNED-BYTE</term>
131
132              <listitem>
133                <para>The argument/return value is of type (UNSIGNED-BYTE 8)</para>
134              </listitem>
135            </varlistentry>
136
137            <varlistentry>
138              <term>:SIGNED-BYTE</term>
139
140              <listitem>
141                <para>The argument/return value is of type (SIGNED-BYTE 8)</para>
142              </listitem>
143            </varlistentry>
144
145            <varlistentry>
146              <term>:UNSIGNED-HALFWORD</term>
147
148              <listitem>
149                <para>The argument/return value is of type (UNSIGNED-BYTE 16)</para>
150              </listitem>
151            </varlistentry>
152
153            <varlistentry>
154              <term>:SIGNED-HALFWORD</term>
155
156              <listitem>
157                <para>The argument/return value is of type (SIGNED-BYTE 16)</para>
158              </listitem>
159            </varlistentry>
160
161            <varlistentry>
162              <term>:UNSIGNED-FULLWORD</term>
163
164              <listitem>
165                <para>The argument/return value is of type (UNSIGNED-BYTE 32)</para>
166              </listitem>
167            </varlistentry>
168
169            <varlistentry>
170              <term>:SIGNED-FULLWORD</term>
171
172              <listitem>
173                <para>The argument/return value is of type (SIGNED-BYTE 32)</para>
174              </listitem>
175            </varlistentry>
176
177            <varlistentry>
178              <term>:UNSIGNED-DOUBLEWORD</term>
179
180              <listitem>
181                <para>The argument/return value is of type (UNSIGNED-BYTE 64)</para>
182              </listitem>
183            </varlistentry>
184
185            <varlistentry>
186              <term>:SIGNED-DOUBLEWORD</term>
187
188              <listitem>
189                <para>The argument/return value is of type (SIGNED-BYTE 64)</para>
190              </listitem>
191            </varlistentry>
192
193            <varlistentry>
194              <term>:SINGLE-FLOAT</term>
195
196              <listitem>
197                <para>The argument/return value is of type SINGLE-FLOAT</para>
198              </listitem>
199            </varlistentry>
200
201            <varlistentry>
202              <term>:DOUBLE-FLOAT</term>
203
204              <listitem>
205                <para>The argument/return value is of type DOUBLE-FLOAT</para>
206              </listitem>
207            </varlistentry>
208
209            <varlistentry>
210              <term>:ADDRESS</term>
211
212              <listitem>
213                <para>The argument/return values
214                is <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
215              </listitem>
216            </varlistentry>
217
218            <varlistentry>
219              <term>:VOID</term>
220
221              <listitem>
222                <para>or NIL Not valid as an argument type specifier; specifies
223                that there is no meaningful return value</para>
224              </listitem>
225            </varlistentry>
226          </variablelist>
227
228          <para>On some platforms, a small positive integer
229          <emphasis>N</emphasis> can also be used as an argument
230          specifier; it indicates that the corresponding argument is a
231          pointer to an <emphasis>N</emphasis>-word structure or union
232          which should be passed by value to the foreign
233          function.  Exactly which foreign structures are passed
234          by value and how is very dependent on the Application
235          Binary Interface (ABI) of the platform; unless you're
236          very familar with ABI detatils (some of which are quite
237          baroque), it's often easier to let higher-level constructs
238          deal with these details.</para>
239        </sect3>
240
241        <sect3 id="External-Entrypoints-and-Named-External-Entrypoints">
242          <title>External Entrypoints and Named External Entrypoints</title>
243          <para>PowerPC machine instructions are always aligned on
244          32-bit boundaries, so the two least significant bits of the
245          first instruction ("entrypoint") of a foreign function are
246          always 0. &CCL; often represents an entrypoint address as
247          a fixnum that's binary-equivalent to the entrypoint address:
248          if<emphasis> E</emphasis> is an entrypoint address expressed
249          as a signed 32-bit integer, then (ash <emphasis>E</emphasis>
250          -2) is an equivalent fixnum representation of that
251          address. An entrypoint address can also be encapsulated in a
252          MACPTR (see FIXTHIS), but that's somewhat less efficient.</para>
253          <para>Although it's possible to use fixnums or macptrs to
254          represent entrypoint addresses, it's somewhat cumbersome to
255          do so. &CCL; can cache the addresses of named external
256          functions in structure-like objects of type
257          CCL:EXTERNAL-ENTRY-POINT (sometimes abbreviated as EEP).
258          Through the use of LOAD-TIME-VALUE, compiled lisp functions
259          are able to reference EEPs as constants; the use of an
260          indirection allows &CCL; runtime system to ensure that the
261          EEP's address is current and correct.</para>
262        </sect3>
263      </sect2>
264
265      <sect2 id="Return-Conventions-for-C-Structures">
266        <title>Return Conventions for C Structures</title>
267        <para> On some platforms, C functions that are defined to
268        return structures do so by reference: they actually
269        accept a first parameter of type "pointer to returned
270        struct/union" - which must be allocated by the caller - and
271        don't return a meaningful value.</para>
272        <para><emphasis>Exactly</emphasis> how a C function that's
273        defined to return a foreign structure does so is dependent on
274        the ABI (and on the size ad composition of the structure/union
275        in many cases.)</para>
276      </sect2>
277    </sect1>
278
279    <sect1 id="Referencing-and-Using-Foreign-Memory-Addresses">
280      <title>Referencing and Using Foreign Memory Addresses</title>
281
282      <sect2 id="Overview-memory-addresses">
283        <title>Overview</title>
284
285        <sect3 id="Basics">
286          <title>Basics</title>
287          <para>For a variety of technical reasons, it isn't generally
288          possible to directly reference arbitrary absolute addresses
289          (such as those returned by the C library function malloc(),
290          for instance) in &CCL;. In &CCL; (and in MCL), such
291          addresses need to be <emphasis>encapsulated</emphasis> in
292          objects of type CCL:MACPTR; one can think of a MACPTR as
293          being a specialized type of structure whose sole purpose is
294          to provide a way of referring to an underlying "raw"
295          address.</para>
296          <para>It's sometimes convenient to blur the distinction
297          between a MACPTR and the address it represents; it's
298          sometimes necessary to maintain that distiction. It's
299          important to remember that a MACPTR is (generally) a
300          first-class Lisp object in the same sense that a CONS cell
301          is: it'll get GCed when it's no longer possible to reference
302          it. The "lifetime" of a MACPTR doesn't generally have
303          anything to do with the lifetime of the block of memory its
304          address points to.</para>
305          <para>It might be tempting to ask "How does one obtain the
306          address encapsulated by a MACPTR ?". The answer to that
307          question is that one doesn't do that (and there's no way to
308          do that): addresses aren't first-class objects, and there's
309          no way to refer to one.</para>
310          <para>Two MACPTRs that encapsulate the same address are EQL
311          to each other.</para>
312          <para>There are a small number of ways to directly create a
313          MACPTR (and there's a fair amount of syntactic sugar built
314          on top of of those primitives.) These primitives will be
315          discussed in greater detail below, but they include:</para>
316
317          <itemizedlist>
318            <listitem>
319            <para>Creating a MACPTR with a specified address, usually
320            via thefunction CCL:%INT-TO-PTR.</para>
321            </listitem>
322            <listitem>
323              <para>Referencing the return valueof a foreign function
324              call (see )that's specified to return an address.</para>
325            </listitem>
326            <listitem>
327              <para>Referencing a memory location that's specified to
328              contain an address.</para>
329            </listitem>
330          </itemizedlist>
331
332          <para>All of these primitive MACPTR-creating operations are
333          usually open-coded by the compiler; it has a fairly good
334          notion of what low-level operations "produce" MACPTRs and
335          which operations "consume" the addresses that the
336          encapsulate, and will usually optimize out the introduction
337          of intermediate MACPTRs in a simple expression.</para>
338          <para>One consequence of the use of MACPTR objects to
339          encapsulate foreign addresses is that (naively)
340          <emphasis>every reference to a foreign address causes a
341          MACPTR to be allocated.</emphasis></para>
342          <para>Consider a code fragment like the following:</para>
343          <programlisting>
344(defun get-next-event ()
345  "get the next event from a hypothetical window system"
346  (loop
347    (let* ((event (#_get_next_window_system_event))) ; via an FF-CALL
348          (unless (null-event-p event)
349            (handle-event event)))))
350</programlisting>
351          <para>As this is written, each call to the (hypothetical)
352          foreign function #_get_next_window_system_event will return
353          a new MACPTR object.  Ignoring for the sake of argument the
354          question of whether this code fragment exhibits a good way
355          to poll for external events (it doesn't), it's not hard to
356          imagine that this loop could execute several millon times
357          per second (producing several million MACPTRs per second.)
358          Clearly, the "naive" approach is impractical in many
359          cases.</para>
360        </sect3>
361
362        <sect3 id="Stack-allocation-of---and-destructive-operations-on---MACPTRs-">
363          <title>Stack allocation of - and destructive operations on - MACPTRs.</title>
364          <para>If certain conditions held in the environment in which
365          GET-NEXT-EVENT ran - namely, if it was guaranteed that
366          neither NULL-EVENT-P nor HANDLE-EVENT cached or otherwise
367          retained their arguments (the "event" pointer) - there'd be
368          a few alternatives to the naive approach. One of those
369          approaches would be to use the primitive function
370          %SETF-MACPTR (described in greater detail below) to
371          destructively modify a MACPTR (to change the value of the
372          address it encapsulates.) The GET-NEXT-EVENT example could
373          be re-written as:</para>
374          <programlisting>
375(defun get-next-event ()
376  (let* ((event (%int-to-ptr 0))) ; create a MACPTR with address 0
377    (loop
378      (%setf-macptr event (#_get_next_window_system_event)) ; re-use it
379      (unless (null-event-p event)
380        (handle-event event)))))
381</programlisting>
382          <para>That version's a bit more realistic: it allocates a
383          single MACPTR outside if the loop, then changes its address
384          to point to the current address of the hypothetical event
385          structure on each loop iteration. If there are a million
386          loop iterations per call to GET-NEXT-EVENT, we're allocating
387          a million times fewer MACPTRs per call; that sounds like a
388          Good Thing.</para>
389          <para>An Even Better Thing would be to advise the compiler
390          that the initial value (the null MACPTR) bound to the
391          variable event has dynamic extent (that value won't be
392          referenced once control leaves the extent of the binding of
393          that variable.) Common Lisp allows us to make such an
394          assertion via a DYNAMIC-EXTENT declaration; &CCL;'s
395          compiler can recognize the "primitive MACPTR-creating
396          operation" involved and can replace it with an equivalent
397          operation that stack-allocates the MACPTR object. If we're
398          not worried about the cost of allocating that MACPTR on
399          every iteration (the cost is small and there's no hidden GC
400          cost), we could move the binding back inside the
401          loop:</para>
402          <programlisting>
403(defun get-next-event ()
404  (loop
405    (let* ((event (%null-ptr))) ; (%NULL-PTR) is shorthand for (%INT-TO-PTR 0)
406      (declare (dynamic-extent event))
407      (%setf-macptr event (#_get_next_window_system_event))
408      (unless (null-event-p event)
409        (handle-event event)))))
410</programlisting>
411          <para>The idiom of binding one or more variables to
412          stack-allocated MACPTRs, then destructively modifying those
413          MACPTRs before executing a body of code is common enough
414          that &CCL; provides a macro (WITH-MACPTRS) that handles
415          all of the gory details. The following version of
416          GET-NEXT-EVENT is semantically equivalent to the previous
417          version, but hopefully a bit more concise:</para>
418          <programlisting>
419(defun get-next-event ()
420  (loop
421    (with-macptrs ((event (#_get_next_window_system_event)))
422      (unless (null-event-p event)
423        (handle-event event)))))
424</programlisting>
425        </sect3>
426
427        <sect3 id="Stack-allocated-memory--and-stack-allocated-pointers-to-it--">
428          <title>Stack-allocated memory (and stack-allocated pointers to it.)</title>
429          <para>Fairly often, the blocks of foreign memory (obtained
430          by malloc or something similar) have well-defined lifetimes
431          (they can safely be freed at some point when it's known that
432          they're no longer needed and it's known that they're no
433          longer referenced.) A common idiom might be:</para>
434          <programlisting>
435(with-macptrs (p (#_allocate_foreign_memory size))
436  (unwind-protect
437    (use-foreign-memory p)
438    (#_deallocate_foreign_memory p)))
439</programlisting>
440          <para>That's not unreasonable code, but it's fairly
441          expensive for a number of reasons: foreign functions calls
442          are themselves fairly expensive (as is UNWIND-PROTECT), and
443          most library routines for allocating and deallocating
444          foreign memory (things like malloc and free) can be fairly
445          expensive in their own right.</para>
446          <para>In the idiomatic code above, both the MACPTR P and the
447          block of memory that's being allocated and freed have
448          dynamic extent and are therefore good candidates for stack
449          allocation. &CCL; provides the %STACK-BLOCK macro, which
450          executes a body of code with one or more variables bound to
451          stack-allocated MACPTRs which encapsulate the addresses of
452          stack-allocated blocks of foreign memory. Using
453          %STACK-BLOCK, the idiomatic code is:</para>
454          <programlisting>
455(%stack-block ((p size))
456  (use-foreign-memory p))
457</programlisting>
458          <para>which is a bit more efficient and a bit more concise
459          than the version presented earlier.</para>
460          <para>%STACK-BLOCK is used as the basis for slightly
461          higher-level things like RLET. (See FIXTHIS for more information
462          about RLET.)</para>
463        </sect3>
464
465        <sect3 id="Caveats-">
466          <title>Caveats.</title>
467          <para>Reading from, writing to, allocating, and freeing
468          foreign memory are all potentially dangerous operations;
469          this is no less true when these operations are performed in
470          &CCL; than when they're done in C or some other
471          lower-level language. In addition, destructive operations on
472          Lisp objects be dangerous, as can stack allocation if it's
473          abused (if DYNAMIC-EXTENT declarations are violated.)
474          Correct use of the constructs and primitives described here
475          is reliable and safe; slightly incorrect use of these
476          constructs and primitives can crash &CCL;.</para>
477        </sect3>
478      </sect2>
479
480      <sect2 id="Foreign-Memory-Addresses-Dictionary">
481        <title>Foreign-Memory-Addresses Dictionary</title>
482        <para>Unless otherwise noted, all of the symbols mentioned
483        below are exported from the CCL package.</para>
484
485        <sect3 id="Scalar-memory-reference">
486          <title>Scalar memory reference</title>
487          <variablelist>
488            <varlistentry>
489              <term>Syntax</term>
490
491              <listitem>
492                <para>%get-signed-byte ptr &#38;optional (offset 0)</para>
493
494                <para>%get-unsigned-byte ptr &#38;optional (offset 0)</para>
495
496                <para>%get-signed-word ptr &#38;optional (offset 0)</para>
497
498                <para>%get-unsigned-word ptr &#38;optional (offset 0)</para>
499
500                <para>%get-signed-long ptr &#38;optional (offset 0)</para>
501
502                <para>%get-unsigned-long ptr &#38;optional (offset 0)</para>
503
504                <para>%%get-signed-longlong ptr &#38;optional (offset 0)</para>
505
506                <para>%%get-unsigned-longlong ptr &#38;optional (offset 0)</para>
507
508                <para>%get-ptr ptr &#38;optional (offset 0)</para>
509
510                <para>%get-single-float ptr &#38;optional (offset 0)</para>
511
512                <para>%get-double-float ptr &#38;optional (offset 0)</para>
513              </listitem>
514            </varlistentry>
515            <varlistentry>
516              <term>Description</term>
517
518              <listitem>
519                <para>References and returns the signed or unsigned 8-bit byte,
520                signed or unsigned 16-bit word, signed or unsigned 32-bit long
521                word, signed or unsigned 64-bit long long word, 32-bit address,
522                32-bit single-float, or 64-bit double-float at the effective byte
523                address formed by adding offset to the address encapsulated by
524                ptr.</para>
525              </listitem>
526            </varlistentry>
527
528            <varlistentry>
529              <term>Arguments</term>
530
531              <listitem>
532
533                <variablelist>
534                  <varlistentry>
535                    <term>ptr</term>
536
537                    <listitem>
538                      <para>A MACPTR</para>
539                    </listitem>
540                  </varlistentry>
541
542                  <varlistentry>
543                    <term>offset</term>
544
545                    <listitem>
546                      <para>A fixnum</para>
547                    </listitem>
548                  </varlistentry>
549                </variablelist>
550              </listitem>
551            </varlistentry>
552          </variablelist>
553
554          <para>All of the memory reference primitives described above can be</para>
555          <para>used with SETF.</para>
556        </sect3>
557
558        <sect3 id="iget-bit--Function-">
559          <title>%get-bit [Function]</title>
560
561          <variablelist>
562            <varlistentry>
563              <term>Syntax</term>
564
565              <listitem>
566                <para>%get-bit ptr bit-offset</para>
567              </listitem>
568            </varlistentry>
569
570            <varlistentry>
571              <term>Description</term>
572
573              <listitem>
574                <para>References and returns the bit-offsetth bit at the address
575                encapsulated by ptr. (Bit 0 at a given address is the most
576                significant bit of the byte at that address.) Can be used with
577                SETF.</para>
578              </listitem>
579            </varlistentry>
580
581            <varlistentry>
582              <term>Arguments</term>
583
584              <listitem>
585                <para>&#x00A0;</para>
586
587                <variablelist>
588                  <varlistentry>
589                    <term>ptr</term>
590
591                    <listitem>
592                      <para>A MACPTR</para>
593                    </listitem>
594                  </varlistentry>
595
596                  <varlistentry>
597                    <term>bit-offset</term>
598
599                    <listitem>
600                      <para>A fixnum</para>
601                    </listitem>
602                  </varlistentry>
603                </variablelist>
604              </listitem>
605            </varlistentry>
606          </variablelist>
607        </sect3>
608
609        <sect3 id="iget-bitfield--Function-">
610          <title>%get-bitfield [Function]</title>
611          <variablelist>
612            <varlistentry>
613              <term>Syntax</term>
614
615              <listitem>
616                <para>%get-bitfield ptr bit-offset width</para>
617              </listitem>
618            </varlistentry>
619
620            <varlistentry>
621              <term>Description</term>
622
623              <listitem>
624                <para>References and returns an unsigned integer composed from the
625                width bits found bit-offsetbits from the address encapsulated by
626                ptr. (The least significant bit of the result is the value of
627                (%get-bit ptr (1- (+ bit-offset width))). Can be used with SETF.</para>
628              </listitem>
629            </varlistentry>
630
631            <varlistentry>
632              <term>Arguments</term>
633
634              <listitem>
635                <para>&#x00A0;</para>
636              </listitem>
637            </varlistentry>
638
639            <varlistentry>
640              <term>ptr</term>
641
642              <listitem>
643                <para>A MACPTR</para>
644
645                <variablelist>
646                  <varlistentry>
647                    <term>bit-offset</term>
648
649                    <listitem>
650                      <para>A fixnum</para>
651                    </listitem>
652                  </varlistentry>
653
654                  <varlistentry>
655                    <term>width</term>
656
657                    <listitem>
658                      <para>A positive fixnum</para>
659                    </listitem>
660                  </varlistentry>
661                </variablelist>
662              </listitem>
663            </varlistentry>
664          </variablelist>
665        </sect3>
666
667        <sect3>
668          <title>%int-to-ptr [Function]</title>
669
670          <variablelist>
671            <varlistentry>
672              <term>Syntax</term>
673
674              <listitem>
675                <para>%int-to-ptr int</para>
676              </listitem>
677            </varlistentry>
678
679            <varlistentry>
680              <term>Description</term>
681
682              <listitem>
683                <para>Creates and returns a MACPTR whose address matches int.</para>
684              </listitem>
685            </varlistentry>
686
687            <varlistentry>
688              <term>Arguments</term>
689
690              <listitem>
691                <para>&#x00A0;</para>
692
693                <variablelist>
694                  <varlistentry>
695                    <term>int</term>
696
697                    <listitem>
698                      <para>An (unsigned-byte 32)</para>
699                    </listitem>
700                  </varlistentry>
701                </variablelist>
702              </listitem>
703            </varlistentry>
704          </variablelist>
705        </sect3>
706
707        <sect3>
708          <title>%inc-ptr [Function]</title>
709
710          <variablelist>
711            <varlistentry>
712              <term>Syntax</term>
713
714              <listitem>
715                <para>%inc-ptr ptr &#38;optional (delta 1)</para>
716              </listitem>
717            </varlistentry>
718
719            <varlistentry>
720              <term>Description</term>
721
722              <listitem>
723                <para>Creates and returns a MACPTR whose address is the address of
724                ptr plus delta. The idiom (%inc-ptr ptr 0) is sometimes used to
725                copy a MACPTR, e.g., to create a new MACPTR encapsulating the same
726                address as ptr.</para>
727              </listitem>
728            </varlistentry>
729
730            <varlistentry>
731              <term>Arguments</term>
732
733              <listitem>
734                <para>&#x00A0;</para>
735
736                <variablelist>
737                  <varlistentry>
738                    <term>ptr</term>
739
740                    <listitem>
741                      <para>A MACPTR</para>
742                    </listitem>
743                  </varlistentry>
744
745                  <varlistentry>
746                    <term>delta</term>
747
748                    <listitem>
749                      <para>A fixnum</para>
750                    </listitem>
751                  </varlistentry>
752                </variablelist>
753              </listitem>
754            </varlistentry>
755          </variablelist>
756        </sect3>
757
758        <sect3>
759          <title>%ptr-to-int [Function]</title>
760
761          <variablelist>
762            <varlistentry>
763              <term>Syntax</term>
764
765              <listitem>
766                <para>%ptr-to-int ptr</para>
767              </listitem>
768            </varlistentry>
769
770            <varlistentry>
771              <term>Description</term>
772
773              <listitem>
774                <para>Returns the address encapsulated by ptr, as an
775                (unsigned-byte 32).</para>
776              </listitem>
777            </varlistentry>
778
779            <varlistentry>
780              <term>Arguments</term>
781
782              <listitem>
783                <para>&#x00A0;</para>
784
785                <variablelist>
786                  <varlistentry>
787                    <term>ptr</term>
788
789                    <listitem>
790                      <para>A MACPTR</para>
791                    </listitem>
792                  </varlistentry>
793                </variablelist>
794              </listitem>
795            </varlistentry>
796          </variablelist>
797        </sect3>
798
799        <sect3>
800          <title>%null-ptr [Macro]</title>
801
802          <variablelist>
803            <varlistentry>
804              <term>Syntax</term>
805
806              <listitem>
807                <para>%null-ptr</para>
808              </listitem>
809            </varlistentry>
810
811            <varlistentry>
812              <term>Description</term>
813
814              <listitem>
815                <para>Equivalent to (%ptr-to-int 0).</para>
816              </listitem>
817            </varlistentry>
818          </variablelist>
819        </sect3>
820
821        <sect3>
822          <title>%null-ptr-p [Function]</title>
823
824          <variablelist>
825            <varlistentry>
826              <term>Syntax</term>
827
828              <listitem>
829                <para>%null-ptr-p ptr</para>
830              </listitem>
831            </varlistentry>
832
833            <varlistentry>
834              <term>Description</term>
835
836              <listitem>
837                <para>Returns T If ptr is a MACPTR encapsulating the address 0,
838                NIL if ptr encapsulates some other address.</para>
839              </listitem>
840            </varlistentry>
841
842            <varlistentry>
843              <term>Arguments</term>
844
845              <listitem>
846                <para>&#x00A0;</para>
847
848                <variablelist>
849                  <varlistentry>
850                    <term>ptr</term>
851
852                    <listitem>
853                      <para>A MACPTR</para>
854                    </listitem>
855                  </varlistentry>
856                </variablelist>
857              </listitem>
858            </varlistentry>
859          </variablelist>
860        </sect3>
861
862        <sect3>
863          <title>%setf-macptr [Function]</title>
864
865          <variablelist>
866            <varlistentry>
867              <term>Syntax</term>
868
869              <listitem>
870                <para>%setf-macptr dest-ptr src-ptr</para>
871              </listitem>
872            </varlistentry>
873
874            <varlistentry>
875              <term>Description</term>
876
877              <listitem>
878                <para>Causes dest-ptr to encapsulate the same address that src-ptr
879                does, then returns dest-ptr.</para>
880              </listitem>
881            </varlistentry>
882
883            <varlistentry>
884              <term>Arguments</term>
885
886              <listitem>
887                <para>&#x00A0;</para>
888
889                <variablelist>
890                  <varlistentry>
891                    <term>dest-ptr</term>
892
893                    <listitem>
894                      <para>A MACPTR</para>
895                    </listitem>
896                  </varlistentry>
897
898                  <varlistentry>
899                    <term>src-ptr</term>
900
901                    <listitem>
902                      <para>A MACPTR</para>
903                    </listitem>
904                  </varlistentry>
905                </variablelist>
906              </listitem>
907            </varlistentry>
908          </variablelist>
909        </sect3>
910
911        <sect3>
912          <title>%incf-ptr [Macro]</title>
913
914          <variablelist>
915            <varlistentry>
916              <term>Syntax</term>
917
918              <listitem>
919                <para>%incf-ptr ptr &#38;optional (delta 1)</para>
920              </listitem>
921            </varlistentry>
922
923            <varlistentry>
924              <term>Description</term>
925
926              <listitem>
927                <para>Destructively modifies ptr, by adding delta to the address
928                it encapsulates. Returns ptr.</para>
929              </listitem>
930            </varlistentry>
931
932            <varlistentry>
933              <term>Arguments</term>
934
935              <listitem>
936                <para>&#x00A0;</para>
937
938                <variablelist>
939                  <varlistentry>
940                    <term>ptr</term>
941
942                    <listitem>
943                      <para>A MACPTR</para>
944                    </listitem>
945                  </varlistentry>
946
947                  <varlistentry>
948                    <term>delta</term>
949
950                    <listitem>
951                      <para>A fixnum</para>
952                    </listitem>
953                  </varlistentry>
954                </variablelist>
955              </listitem>
956            </varlistentry>
957          </variablelist>
958        </sect3>
959
960        <sect3>
961          <title>with-macptrs [Macro]</title>
962
963          <variablelist>
964            <varlistentry>
965              <term>Syntax</term>
966
967              <listitem>
968                <para>with-macptrs (var expr)* &#38;body body</para>
969              </listitem>
970            </varlistentry>
971
972            <varlistentry>
973              <term>Description</term>
974
975              <listitem>
976                <para>Executes body in an environment in which each var is bound
977                to a stack-allocated macptr which encapsulates the foreign address
978                yielded by the corresponding expr. Returns whatever value(s) body
979                returns.</para>
980              </listitem>
981            </varlistentry>
982
983            <varlistentry>
984              <term>Arguments</term>
985
986              <listitem>
987                <para>&#x00A0;</para>
988
989                <variablelist>
990                  <varlistentry>
991                    <term>var</term>
992
993                    <listitem>
994                      <para>A symbol (variable name)</para>
995                    </listitem>
996                  </varlistentry>
997
998                  <varlistentry>
999                    <term>expr</term>
1000
1001                    <listitem>
1002                      <para>A MACPTR-valued expression</para>
1003                    </listitem>
1004                  </varlistentry>
1005                </variablelist>
1006              </listitem>
1007            </varlistentry>
1008          </variablelist>
1009        </sect3>
1010
1011        <sect3>
1012          <title>%stack-block [Macro]</title>
1013
1014          <variablelist>
1015            <varlistentry>
1016              <term>Syntax</term>
1017
1018              <listitem>
1019                <para>%stack-block (var expr)* &#38;body body</para>
1020              </listitem>
1021            </varlistentry>
1022
1023            <varlistentry>
1024              <term>Description</term>
1025
1026              <listitem>
1027                <para>Executes body in an environment in which each var is bound
1028                to a stack-allocated macptr which encapsulates the address of a
1029                stack-allocated region of size expr bytes. Returns whatever
1030                value(s) body returns.</para>
1031              </listitem>
1032            </varlistentry>
1033
1034            <varlistentry>
1035              <term>Arguments</term>
1036
1037              <listitem>
1038                <para>&#x00A0;</para>
1039
1040                <variablelist>
1041                  <varlistentry>
1042                    <term>var</term>
1043
1044                    <listitem>
1045                      <para>A symbol (variable name)</para>
1046                    </listitem>
1047                  </varlistentry>
1048
1049                  <varlistentry>
1050                    <term>expr</term>
1051
1052                    <listitem>
1053                      <para>An expression which should evaluate to a non-negative
1054                      fixnum</para>
1055                    </listitem>
1056                  </varlistentry>
1057                </variablelist>
1058              </listitem>
1059            </varlistentry>
1060          </variablelist>
1061        </sect3>
1062
1063          <sect3>
1064            <title>make-cstring [Function]</title>
1065
1066            <variablelist>
1067              <varlistentry>
1068                <term>Syntax</term>
1069
1070                <listitem>
1071                  <para>make-cstring string</para>
1072                </listitem>
1073              </varlistentry>
1074
1075              <varlistentry>
1076                <term>Description</term>
1077
1078                <listitem>
1079                  <para>Allocates a block of memory (via malloc) of length (1+
1080                  (length string)). Copies the string to this block and appends a
1081                  trailing NUL byte; returns a MACPTR to the block.</para>
1082                </listitem>
1083              </varlistentry>
1084
1085              <varlistentry>
1086                <term>Arguments</term>
1087
1088                <listitem>
1089                  <para>&#x00A0;</para>
1090
1091                  <variablelist>
1092                    <varlistentry>
1093                      <term>string</term>
1094
1095                      <listitem>
1096                        <para>A lisp string</para>
1097                      </listitem>
1098                    </varlistentry>
1099                  </variablelist>
1100                </listitem>
1101              </varlistentry>
1102            </variablelist>
1103          </sect3>
1104
1105        <sect3>
1106          <title>with-cstrs [Macro]</title>
1107
1108          <variablelist>
1109            <varlistentry>
1110              <term>Syntax</term>
1111
1112              <listitem>
1113                <para>with-cstrs (var string)* &#38;body body</para>
1114              </listitem>
1115            </varlistentry>
1116
1117            <varlistentry>
1118              <term>Description</term>
1119
1120              <listitem>
1121                <para>Executes body in an environment in which each var is bound
1122                to a stack-allocated macptr which encapsulates the %address of a
1123                stack-allocated region of into which each string (and a trailing
1124                NUL byte) has been copied. Returns whatever value(s) body returns.</para>
1125              </listitem>
1126            </varlistentry>
1127
1128            <varlistentry>
1129              <term>Arguments</term>
1130
1131              <listitem>
1132                <para>&#x00A0;</para>
1133
1134                <variablelist>
1135                  <varlistentry>
1136                    <term>var</term>
1137
1138                    <listitem>
1139                      <para>A symbol (variable name)</para>
1140                    </listitem>
1141                  </varlistentry>
1142
1143                  <varlistentry>
1144                    <term>string</term>
1145
1146                    <listitem>
1147                      <para>An expression which should evaluate to a lisp string</para>
1148                    </listitem>
1149                  </varlistentry>
1150                </variablelist>
1151              </listitem>
1152            </varlistentry>
1153          </variablelist>
1154        </sect3>
1155
1156        <sect3>
1157          <title>%get-cstring [Function]</title>
1158
1159          <variablelist>
1160            <varlistentry>
1161              <term>Syntax</term>
1162
1163              <listitem>
1164                <para>%get-cstring ptr</para>
1165              </listitem>
1166            </varlistentry>
1167
1168            <varlistentry>
1169              <term>Description</term>
1170
1171              <listitem>
1172                <para>Interprets ptr as a pointer to a (NUL -terminated) C string;
1173                returns an equivalent lisp string.</para>
1174              </listitem>
1175            </varlistentry>
1176
1177            <varlistentry>
1178              <term>Arguments</term>
1179
1180              <listitem>
1181                <para></para>
1182
1183                <variablelist>
1184                  <varlistentry>
1185                    <term>ptr</term>
1186
1187                    <listitem>
1188                      <para>A MACPTR</para>
1189                    </listitem>
1190                  </varlistentry>
1191                </variablelist>
1192              </listitem>
1193            </varlistentry>
1194          </variablelist>
1195        </sect3>
1196
1197        <sect3>
1198          <title>%str-from-ptr [Function]</title>
1199
1200          <variablelist>
1201            <varlistentry>
1202              <term>Syntax</term>
1203
1204              <listitem>
1205                <para>%str-from-ptr ptr length</para>
1206              </listitem>
1207            </varlistentry>
1208
1209            <varlistentry>
1210              <term>Description</term>
1211
1212              <listitem>
1213                <para>Returns a lisp string of length <varname>length</varname>,
1214                whose contents are initialized from the bytes at<varname> ptr.</varname>
1215                </para>
1216              </listitem>
1217            </varlistentry>
1218
1219            <varlistentry>
1220              <term>Arguments</term>
1221
1222              <listitem>
1223                <para><variablelist><varlistentry><term>ptr</term><listitem><para>A
1224                MACPTR</para></listitem></varlistentry><varlistentry><term>length</term><listitem><para>a
1225                non-negative fixnum</para></listitem></varlistentry></variablelist></para>
1226              </listitem>
1227            </varlistentry>
1228          </variablelist>
1229        </sect3>
1230      </sect2>
1231    </sect1>
1232
1233    <sect1 id="The-Interface-Database">
1234      <title>The Interface Database</title>
1235
1236      <sect2 id="interface-database-Overview">
1237        <title>Overview</title>
1238        <para>&CCL; uses a set of database files which contain
1239        foreign type, record, constant, and function definitions
1240        derived from the operating system's header files, be that
1241        Linux or Darwin.  An archive containing these database files
1242        (and the shell scripts which were used in their creation) is
1243        available; see the Distributions page for information about
1244        obtaining current interface database files.</para>
1245        <para>Not surprisingly, different platforms use different database files.</para>
1246        <para>&CCL; defines reader macros that consult these databases:</para>
1247        <itemizedlist>
1248          <listitem>
1249            <para>#$foo looks up the value of the constant definition of foo</para>
1250          </listitem>
1251          <listitem>
1252            <para>#_foo looks up the foreign function definition for foo</para>
1253          </listitem>
1254       
1255        </itemizedlist>
1256        <para>In both cases, the symbol foo is interned in the "OS"
1257        package. The #$ reader macro has the side-effect of defining
1258        foo as a constant (as if via DEFCONSTANT); the #_ reader macro
1259        has the side effect of defining foo as a macro which will
1260        expand into an (EXTERNAL-CALL form.)</para>
1261        <para>It's important to remember that the side-effect happens
1262        when the form containing the reader macro is
1263        read. Macroexpansion functions that expand into forms which
1264        contain instances of those reader macros don't do what one
1265        might think that they do, unless the macros are expanded in
1266        the same lisp session as the reader macro was read in.</para>
1267        <para>In addition, references to foreign type,
1268        structure/union, and field names (when used in the RREF/PREF
1269        and RLET macros) will cause these database files to be
1270        consulted.</para>
1271        <para>Since the &CCL; sources contain instances of these
1272        reader macros (and references to foreign record types and
1273        fields), compiling &CCL; from those sources depends on the
1274        ability to find and use (see <xref
1275        linkend="Building-the-heap-image"/>).</para>
1276      </sect2>
1277
1278      <sect2 id="Other-issues">
1279        <title>Other issues:</title>
1280        <itemizedlist>
1281          <listitem>
1282            <para>&CCL; now preserves the case of external symbols
1283            in itsdatabase files. See for information about case in
1284            foreign symbol names.</para>
1285          </listitem>
1286          <listitem>
1287            <para>The Linux databases are derived from a somewhat
1288            arbitrary set of Linux header files. Linux is enough of a
1289            moving target that it may be difficult to define a standard,
1290            reference set of interfaces from which to derive a standard,
1291            reference set of database files.This seems to be less of
1292            an issue with Darwin and FreeBSD.</para>
1293          </listitem>
1294        </itemizedlist>
1295        <para>For information about building the database files,
1296        see <xref linkend="The-Interface-Translator"/>.</para>
1297      </sect2>
1298    </sect1>
1299
1300    <sect1 id="Using-Interface-Directories">
1301      <title>Using Interface Directories</title>
1302
1303      <sect2 id="Interface-Directory-Overview">
1304        <title>Overview</title>
1305        <para>As distributed, the "ccl:headers;" (for LinuxPPC)
1306        directory is organized like:</para>
1307        <programlisting>
1308headers/
1309headers/gl/
1310headers/gl/C/
1311headers/gl/C/populate.sh
1312headers/gl/constants.cdb
1313headers/gl/functions.cdb
1314headers/gl/records.cdb
1315headers/gl/objc-classes.cdb
1316headers/gl/objc-methods.cdb
1317headers/gl/types.cdb
1318headers/gnome/
1319headers/gnome/C/
1320headers/gnome/C/populate.sh
1321headers/gnome/constants.cdb
1322headers/gnome/functions.cb
1323headers/gnome/records.cdb
1324headers/gnome/objc-classes.cdb
1325headers/gnome/objc-methods.cdb
1326headers/gnome/types.cdb
1327headers/gtk/
1328headers/gtk/C/
1329headers/gtk/C/populate.sh
1330headers/gtk/constants.cdb
1331headers/gtk/functions.cdb
1332headers/gtk/records.cdb
1333headers/gtk/objc-classes.cdb
1334headers/gtk/objc-methods.cdb
1335headers/gtk/types.cdb
1336headers/libc/
1337headers/libc/C/
1338headers/libc/C/populate.sh
1339headers/libc/constants.cdb
1340headers/libc/functions.cdb
1341headers/libc/records.cdb
1342headers/libc/objc-classes.cdb
1343headers/libc/objc-methods.cdb
1344headers/libc/types.cdb
1345</programlisting>
1346        <para>e.g, as a set of parallel subdirectories, each with a
1347        lowercase name and each of which contains a set of 6 database
1348        files and a "C" subdirectory which contains a shell script
1349        used in the database creation process.</para>
1350        <para>As one might assume, the database files in each of these
1351        subdirectories contain foreign type, constant, and function
1352        definitions - as well as ObjC class and method info -that
1353        correspond (roughly) to the information contained in the
1354        header files associated with a "-dev" package in a Linux
1355        distribution.  "libc" corresponds pretty closely to the
1356        interfaces associated with "glibc/libc6" header files, "gl"
1357        corresponds to an "openGL+GLUT" developmnent package, "gtk"
1358        and "gnome" contain interface information from the GTK+1.2 and
1359        GNOME libraries, respectively.</para>
1360        <para>For Darwin, the "ccl:darwin-headers" directory contains
1361        a "libc" subdirectory, whose contents roughly correspond to
1362        those of "/usr/include" under Darwin, as well as
1363        subdirectories corresponding to the MacOSX Carbon and Cocoa
1364        frameworks.</para>
1365        <para>To see the precise set of .h files used to generate the
1366        database files in a given interface directory, consult the
1367        corresponding "populate.sh" shell script (in the interface
1368        directory's "C" subdirectory.)</para>
1369        <para>The intent is that this initial set can be augmented to
1370        meet local needs, and that this can be done in a fairly
1371        incremental fashion: one needn't have unrelated header files
1372        installed in order to generate interface databases for a
1373        package of interest.</para>
1374        <para>Hopefully, this scheme will also make it easier to
1375        distribute patches and bug fixes.</para>
1376        <para>&CCL; maintains a list of directories; when looking
1377        for a foreign type, constant, function, or record definition,
1378        it'll consult the database files in each directory on that
1379        list. Initially, the list contains an entry for the "libc"
1380        interface directory. &CCL; needs to be explicitly told to
1381        look in other interface directories should it need to do
1382        so.</para>
1383      </sect2>
1384
1385      <sect2 id="Creating-new-interface-directories">
1386        <title>Creating new interface directories</title>
1387        <para>This example refers to "ccl:headers;", which is
1388        appropriate for LinuxPPC. The procedure's analogous under
1389        Darwin, where the "ccl:darwin-headers;" directory would be
1390        used instead.</para>
1391        <para>To create a new interface directory, "foo", and a set of
1392        database files in that directory:</para>
1393        <orderedlist continuation="restarts" inheritnum="ignore">
1394          <listitem>
1395            <para>Create a subdirectory of &#34;ccl:headers;&#34; named
1396            &#34;foo&#34;.</para>
1397          </listitem>
1398
1399          <listitem>
1400            <para>Create a subdirectory of &#34;ccl:headers;foo;&#34; named
1401            &#34;C&#34;.</para>
1402          </listitem>
1403
1404          <listitem>
1405            <para>Create a file in &#34;ccl:headers;foo;C;&#34; named
1406            &#34;populate.sh&#34;.</para>
1407
1408            <para>One way of accomplishing the above steps is:</para>
1409
1410            <programlisting format="linespecific">? (close (open &#34;ccl:headers;foo;C;populate.sh&#34; :direction :output :
1411               if-does-not-exist :create :if-exists :overwrite))</programlisting>
1412          </listitem>
1413
1414          <listitem>
1415            <para>Edit the file created above, using the &#34;populate.sh&#34;
1416            files in the distribution as guidelines.</para>
1417
1418            <para>The file might wind up looking something like:</para>
1419
1420            <programlisting format="linespecific">#/bin/sh
1421h-to-ffi.sh `foo-config -cflags` /usr/include/foo/foo.h</programlisting>
1422          </listitem>
1423        </orderedlist>
1424
1425        <para>Refer to <xref linkend="The-Interface-Translator"/> for
1426        information about running the interface translator and .ffi
1427        parser.</para>
1428        <para>Assuming that all went well, there should now be .cdb
1429        files in "ccl:headers;foo;". You can then do
1430        <programlisting>
1431? (use-interface-dir :foo)
1432        </programlisting> 
1433        whenever you need to
1434        access the foreign type information in those database
1435        files.</para>
1436      </sect2>
1437    </sect1>
1438
1439    <sect1 id="Using-Shared-Libraries">
1440      <title>Using Shared Libraries</title>
1441
1442      <sect2 id="Shared-Library-Overview">
1443        <title>Overview</title>
1444
1445        <para>&CCL; provides facilities to open and close shared
1446        libraries.</para>
1447        <para>"Opening" a shared library, which is done with <xref
1448        linkend="f_open-shared-library"/>, maps the library's code and
1449        data into &CCL;'s address space and makes its exported
1450        symbols accessible to &CCL;.</para>
1451        <para>"Closing" a shared library, which is done with <xref
1452        linkend="f_close-shared-library"/>, unmaps the library's code
1453        and and removes the library's symbols from the global
1454        namespace.</para>
1455        <para>A small number of shared libraries (including libc,
1456        libm, libdl under Linux, and the "system" library under
1457        Darwin) are opened by the lisp kernel and can't be
1458        closed.</para>
1459        <para>&CCL; uses data structures of type
1460        EXTERNAL-ENTRY-POINT to map a foreign function name (string)
1461        to that foreign function's <emphasis>current</emphasis>
1462        address. (A function's address may vary from session to
1463        session as different versions of shared libraries may load at
1464        different addresses; it may vary within a session for similar
1465        reasons.)</para>
1466        <para>An EXTERNAL-ENTRY-POINT whose address is known is said
1467        to be <emphasis>resolved</emphasis>. When an external entry
1468        point is resolved, the shared library which defines that entry
1469        point is noted; when a shared library is closed, the entry
1470        points that it defines are made unresolved.  An
1471        EXTERNAL-ENTRY-POINT must be in the resolved state in order to
1472        be FF-CALLed; calling an unresolved entry point causes a "last
1473        chance" attempt to resolve it. Attempting to resolve an
1474        entrypoint that was defined in a closed library will cause an
1475        attempt to reopen that library.</para>
1476        <para>&CCL; keeps track of all libraries that have been
1477        opened in a lisp session. When a saved application is first
1478        started, an attempt is made to reopen all libraries that were
1479        open when the image was saved, and an attempt is made to
1480        resolve all entrypoints that had been referenced when the
1481        image was saved. Either of these attempts can fail "quietly",
1482        leaving some entry points in an unresolved state.</para>
1483        <para>Linux shared libraries can be referred to either by a
1484        string which describes their full pathname or by their
1485        <emphasis>soname</emphasis>, a shorter string that can be
1486        defined when the library is created. The dynamic linker
1487        mechanisms used in Linux make it possible (through a series of
1488        filesystem links and other means) to refer to a library via
1489        several names; the library's soname is often the most
1490        appropriate identifier.</para>
1491        <para>sonames are often less version-specific than other names
1492        for libraries; a program that refers to a library by the name
1493        "libc.so.6" is more portable than one which refers to
1494        "libc-2.1.3.so" or to "libc-2.2.3.so", even though the latter
1495        two names might each be platform-specific aliases of the
1496        first.</para>
1497        <para>All of the global symbols described below are exported
1498        from the CCL package.</para>
1499      </sect2>
1500
1501      <sect2 id="Limitations-and-known-bugs--1-">
1502        <title>Limitations and known bugs</title>
1503        <itemizedlist>
1504          <listitem>
1505            <para>Don't get me started.</para>
1506          </listitem>
1507          <listitem>
1508            <para>The underlying functionality has a poor notion of
1509            dependency;it's not always possible to open libraries that
1510            depend on unopened libraries, but it's possible to close
1511            libraries on which other libraries depend. It
1512            <emphasis>may</emphasis> be possible to generate
1513            more explicit dependency information by parsing the output
1514            of the Linux ldd and ldconfig programs.</para>
1515          </listitem>
1516       
1517        </itemizedlist>
1518      </sect2>
1519
1520      <sect2 id="Darwin-Notes">
1521        <title>>Darwin Notes</title>
1522        <para>Darwin shared libraries come in two (basic) flavors:</para>
1523        <itemizedlist>
1524          <listitem>
1525            <para>"dylibs" (which often have the extension".dylib")
1526            are primarily intended to be linked against atcompile/link
1527            time. They can be loaded dynamically,<emphasis>but can't
1528            be unloaded</emphasis>. Accordingly,OPEN-SHARED-LIBRARY
1529            can be used to open a .dylib-style library;calling
1530            CLOSE-SHARED-LIBRARY on the result of such a callproduces
1531            a warning, and has no other effect.It appears that (due to
1532            an OS bug) attempts to open .dylibshared-libraries that
1533            are already open can cause memory corruptionunless the
1534            full pathname of the .dylib file is specified on thefirst
1535            and all subsequent calls.</para>
1536          </listitem>
1537          <listitem>
1538            <para>"bundles" are intended to serve as application
1539            extensions; they can be opened multiple times (creating
1540            multiple instances of the library!) and closed
1541            properly.</para>
1542          </listitem>
1543        </itemizedlist>
1544        <para>Thanks to Michael Klingbeil for getting both kinds of
1545        Darwin shared libraries working in &CCL;.</para>
1546      </sect2>
1547    </sect1>
1548
1549    <sect1 id="The-Interface-Translator">
1550      <title>The Interface Translator</title>
1551
1552      <sect2 id="Inteface-translator-overview">
1553        <title>Overview</title>
1554        <para>&CCL; uses an interface translation system based on the FFIGEN
1555        system, which is described at
1556        http://www.ccs.neu.edu/home/lth/ffigen/.
1557        The interface translator makes
1558        the constant, type, structure, and function definitions in a set of
1559        C-language header files available to lisp code.</para>
1560        <para>The basic idea of the FFIGEN scheme is to use the C
1561        compiler's frontend and parser to translate .h files into
1562        semantically equivalent .ffi files, which represent the
1563        definitions from the headers using a syntax based on
1564        S-expressions.  Lisp code can then concentrate on the .ffi
1565        representation, without having to concern itself with the
1566        semantics of header file inclusion or the arcana of C
1567        parsing.</para>
1568        <para>The original FFIGEN system used a modified version of
1569        the LCC C compiler to produce .ffi files. Since many LinuxPPC
1570        header files contain GCC-specific constructs, &CCL;'s
1571        translation system uses a modified version of GCC (called,
1572        somewhat confusingly, ffigen.)</para>
1573        <para>A version of ffigen based on GCC-4.0 was developed
1574        during the spring and summer of 2005.  Sources (diffs relative
1575        to the GCC-4.0 release) are available here, and binaries are
1576        available for DarwinPPC and for LinuxPPC.  These versions
1577        should be insensitive to to the version of GCC (and its
1578        preprocessor) installed on the system.</para>
1579        <para>An older version was developed in 2001-2002; it depended
1580        on the installed version of GCC being 2.95.  It may still be
1581        of interest for people unable to run the GCC-4.0-based version
1582        for whatever reason.</para>
1583        <para>A LinuxPPC binary of this older version is available at
1584        ftp://clozure.com/pub/ffigen-0.1.tar.gz, and LinuxPPC source
1585        differences are at
1586        ftp://clozure.com/pub/ffigen-src.tar.gz.</para>
1587        <para>For Darwin, the binary of the older FFIGEN is available
1588        at ftp://clozure.com/pub/ffigen-darwin.tar.gz, and the source
1589        differences are at
1590        ftp://clozure.com/pub/ffigen-darwin-src.tar.gz.</para>
1591        <para>A shell script (distributed with the source and binary
1592        packages) called h-to-ffi.sh reads a specified .h file (and
1593        optional preprocessor arguments) and writes a (hopefully)
1594        equivalent .ffi file to standard output, calling the installed
1595        C preprocessor and the ffigen program with appropriate
1596        arguments.</para>
1597        <para>For each interface directory (see FIXTHIS)
1598        <emphasis>subdir</emphasis> distributed with &CCL;, a shell
1599        script (distributed with &CCL; as
1600        "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"
1601        ("ccl:darwin-headers;<emphasis>subdir</emphasis>;C;populate.sh"
1602        for Darwin)) calls h-to-ffi.sh on a large number of the header
1603        files in /usr/include (or some other <emphasis>system header
1604        path</emphasis>) and creates a parallel directory tree in
1605        "ccl:headers;<emphasis>subdir</emphasis>;C;<emphasis>system</emphasis>;<emphasis>header</emphasis>;<emphasis>path</emphasis>;"
1606        (or
1607        "ccl:darwin-headers;<emphasis>subdir</emphasis>;C;<emphasis>system</emphasis>;<emphasis>header</emphasis>;<emphasis>path</emphasis>;"),
1608        populating that directory with .ffi files.</para>
1609        <para>A lisp function defined in "ccl:library;parse-ffi.lisp"
1610        reads the .ffi files in a specified interface directory
1611        <emphasis>subdir</emphasis> and generates new versions of the
1612        databases (files with the extension .cdb).</para>
1613        <para>The CDB databases are used by the #$ and #_ reader
1614        macros and are used in the expansion of RREF, RLET, and
1615        related macros.</para>
1616      </sect2>
1617
1618      <sect2 id="Details--rebuilding-the-CDB-databases--step-by-step">
1619        <title>Details: rebuilding the CDB databases, step by step</title>
1620        <orderedlist>
1621          <listitem>
1622            <para>Ensure that the FFIGEN program is installed. See
1623            the"README" file in the source or binary archive for
1624            specificinstallation instructions.This example assumes
1625            LinuxPPC; for 32-bit DarwinPPC,
1626            substitute"ccl:darwin-headers;" for "ccl:headers;".  For
1627            64-bit DarwinPPC,substitute
1628            "ccl:darwin-headers64;".</para>
1629          </listitem>
1630          <listitem>
1631            <para>Edit the
1632            "ccl:headers;<emphasis>subdir</emphasis>;C;populate.sh"shell
1633            script. When you're confident that the files
1634            andpreprocessor options match your environment, cd to
1635            the"ccl:headers;<emphasis>subdir</emphasis>;C;" directory
1636            andinvoke ./populate.sh. Repeat this step until you're
1637            able tocleanly translate all files refrenced in the shell
1638            script.</para>
1639          </listitem>
1640          <listitem>
1641            <para>Run &CCL;:
1642            <programlisting>
1643? (require "PARSE-FFI")
1644PARSE-FFI
1645
1646? (parse-standard-ffi-files :SUBDIR)
1647;;; lots of output ... after a while, shiny new .cdb files should
1648;;; appear in "ccl:headers;subdir;"
1649;;; (or "ccl:darwin-headers;subdir;" under Darwin)
1650</programlisting></para>
1651          </listitem>
1652        </orderedlist>
1653      </sect2>
1654    </sect1>
1655
1656    <sect1 id="Case-sensitivity-of-foreign-names-in-&CCL;">
1657      <title>Case-sensitivity of foreign names in &CCL;</title>
1658
1659      <sect2 id="Case-sensitivity-overview">
1660        <title>Overview</title>
1661        <para>As of release 0.11, &CCL; addresses the fact that
1662        foreign type, constant, record, field, and function nams are
1663        case-sensitive and provides mechanisms to refer to these names
1664        via lisp symbols.</para>
1665        <para>Previous versions of &CCL; have tried to ignore that
1666        fact, under the belief that case conflicts were rare and that
1667        many users (and implementors) would prefer not to deal with
1668        case-related issues. The fact that some information in the
1669        interface databases was incomplete or inaccessable because of
1670        this policy made it clearer that the policy was untenable. I
1671        can't claim that the approach described here is aesthetically
1672        pleasing, but I can honestly say that it's less unpleasant
1673        than other approaches that I'd thought of. I'd be interested
1674        to hear alternate proposals.</para>
1675        <para>The issues described here have to do with how lisp
1676        symbols are used to denote foreign functions, constants,
1677        types, records, and fields. It doesn't affect how other lisp
1678        objects are sometimes used to denote foreign objects. For
1679        instance, the first argument to the EXTERNAL-CALL macros is
1680        now and has always been a case-sensitive string.</para>
1681      </sect2>
1682
1683      <sect2 id="Foreign-constant-and-function-names">
1684        <title>Foreign constant and function names</title>
1685        <para>The primary way of referring to foreign constant and
1686        function names in &CCL; is via the #$ and #_ reader
1687        macros. These reader macro functions each read a symbol into
1688        the "OS" package, look up its constant or function definition
1689        in the interface database, and assign the value of the
1690        constant to the symbol or install a macroexpansion function on
1691        the symbol.</para>
1692        <para>In order to observe case-sensitivity, the reader-macros
1693        now read the symbol with (READTABLE-CASE :PRESERVE) in
1694        effect.</para>
1695        <para>This means that it's necessary to type the foreign
1696        constant or function name in correct case, but it isn't
1697        necessary to use any special escaping constructs when writing
1698        the variable name. For instance:</para>
1699        <programlisting>
1700(#_read fd buf n) ; refers to foreign symbol "read"
1701(#_READ fd buf n) ; refers to foreign symbol "READ", which may
1702; not exist ...
1703#$o_rdonly ; Probably doesn't exist
1704#$O_RDONLY ; Exists on most platforms
1705</programlisting>
1706      </sect2>
1707
1708      <sect2 id="Foreign-type--record--and-field-names">
1709        <title>Foreign type, record, and field names</title>
1710        <para>Constructs like RLET expect a foreign type or record
1711        name to be denoted by a symbol (typically a keyword); RREF
1712        (and PREF) expect an "accessor" form, typically a keyword
1713        formed by concatenating a foreign type or record name with a
1714        sequence of one or more foreign field names, separated by
1715        dots. These names are interned by the reader as other lisp
1716        symbols are, with an arbitrary value of READTABLE-CASE in
1717        effect (typically :UPCASE.) It seems like it would be very
1718        tedious to force users to manually escape (via vertical bar or
1719        backslash syntax) all lowercase characters in symbols used to
1720        specify foreign type, record, and field names (especially
1721        given that many traditional POSIX structure, type, and field
1722        names are entirely lowercase.)</para>
1723        <para>The approach taken by &CCL; is to allow the symbols
1724        (keywords) used to denote foreign type, record, and field
1725        names to contain angle brackets (<literal>&lt;</literal> and
1726        <literal>&gt;</literal>). Such symbols are translated to
1727        foreign names via the following set of conventions:</para>
1728        <itemizedlist>
1729          <listitem>
1730            <para>All instances of &lt; and &gt; in the symbol's pname
1731            are balanced and don't nest.</para>
1732          </listitem>
1733          <listitem>
1734            <para>Any alphabetic characters in the symbol's pname
1735            thataren't enclosed in angle brackets are treated as
1736            lower-case,regardless of the value of READTABLE-CASE and
1737            regardless of the case in which they were written.</para>
1738          </listitem>
1739          <listitem>
1740            <para>Alphabetic characters that appear within angle
1741            brackets aremapped to upper-case, again regardless of how
1742            they were written orinterned.</para>
1743          </listitem>
1744        </itemizedlist>
1745        <para>There may be many ways of "escaping" (with angle
1746        brackets) sequences of upper-case and non-lower-case
1747        characters in a symbol used to denote a foreign name. When
1748        translating in the other direction, &CCL; always escapes the
1749        longest sequence that starts with an upper-case character and
1750        doesn't contain a lower-case character.</para>
1751        <para>It's often preferable to use this canonical form of a
1752        foreign type name.</para>
1753        <para>The accessor forms used by PREF/RREF should be viewed as
1754        a series of foreign type/record and field names; upper-case
1755        sequences in the component names should be escaped with angle
1756        brackets, but those sequences shouldn't span components. (More
1757        simply, the separating dots shouldn't be enclosed, even if
1758        both surrounding characters need to be.)</para>
1759        <para>Older POSIX code tends to use lower-case exclusively for
1760        type, record, and field names; there are only a few cases in
1761        the &CCL; sources where mixed-case names need to be
1762        escaped.</para>
1763       
1764      </sect2>
1765
1766      <sect2 id="Examples--1-">
1767        <title>Examples</title>
1768        <programlisting>
1769;;; Allocate a record of type "window".
1770(rlet ((w :window)) ...)
1771;;; Allocate a record of type "Window", which is probably a
1772;;;  different type
1773(rlet ((w :&lt;w&gt;indow)) ...)
1774;;; This is equivalent to the last example
1775(rlet ((w :&lt;w&gt;INDOW)))
1776</programlisting>
1777      </sect2>
1778    </sect1>
1779
1780    <sect1 id="Tutorial--Using-Basic-Calls-and-Types">
1781      <title>Tutorial: Using Basic Calls and Types</title>
1782      <para>This tutorial is meant to cover the basics of &CCL; for
1783      calling external C functions and passing data back and forth.
1784      These basics will provide the foundation for more advanced
1785      techniques which will allow access to the various external
1786      libraries and toolkits.</para>
1787      <para>The first step is to start with a simple C dynamic library
1788      in order to actually observe what is actually passing between
1789      &CCL; and C.  So, some C code is in order:</para>
1790      <para>Create the file typetest.c, and put the following code
1791      into it:</para>
1792      <programlisting>
1793
1794#include &lt;stdio.&gt;
1795
1796void
1797void_void_test(void)
1798{
1799    printf("Entered %s:\n", __FUNCTION__);
1800    printf("Exited  %s:\n", __FUNCTION__);
1801    fflush(stdout);
1802}
1803
1804signed char
1805sc_sc_test(signed char data)
1806{
1807    printf("Entered %s:\n", __FUNCTION__);
1808    printf("Data In: %d\n", (signed int)data);
1809    printf("Exited  %s:\n", __FUNCTION__);
1810    fflush(stdout);
1811    return data;
1812}
1813
1814unsigned char
1815uc_uc_test(unsigned char data)
1816{
1817    printf("Entered %s:\n", __FUNCTION__);
1818    printf("Data In: %d\n", (signed int)data);
1819    printf("Exited  %s:\n", __FUNCTION__);
1820    fflush(stdout);
1821    return data;
1822}
1823      </programlisting>
1824      <para>This defines three functions.  If you're familiar with C,
1825      notice that there's no <literal>main()</literal>, because we're
1826      just building a library, not an executable.</para>
1827      <para>The function <literal>void_void_test()</literal> doesn't
1828      take any parameters, and doesn't return anything, but it prints
1829      two lines to let us know it was called.
1830      <literal>sc_sc_test()</literal> takes a signed char as a
1831      parameter, prints it, and returns it.
1832      <literal>uc_uc_test()</literal> does the same thing, but with an
1833      unsigned char.  Their purpose is just to prove to us that we
1834      really can call C functions, pass them values, and get values
1835      back from them.</para>
1836      <para>This code is compiled into a dynamic library on OS X
1837      10.3.4 with the command:</para>
1838      <programlisting>
1839
1840gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
1841    -install_name ./libtypetest.dylib
1842      </programlisting>
1843      <tip><para>Users of 64-bit platforms may need to pass options such
1844      as "-m64" to gcc, may need to give the output library a different
1845      extension (such as ".so"), and may need to user slightly different
1846      values for other options in order to create an equivalent test
1847      library.</para></tip>
1848
1849      <para>The -dynamiclib tells gcc that we will be compiling this
1850      into a dynamic library and not an executable binary program.
1851      The output filename is "libtypetest.dylib".  Notice that we
1852      chose a name which follows the normal OS X convention, being in
1853      the form "libXXXXX.dylib", so that other programs can link to
1854      the library.  &CCL; doesn't need it to be this way, but it is
1855      a good idea to adhere to existing conventions.</para>
1856      <para>The -install_name flag is primarily used when building OS
1857      X "bundles".  In this case, we are not using it, so we put a
1858      placeholder into it, "./libtypetest.dylib".  If we wanted to use
1859      typetest in a bundle, the -install_name argument would be a
1860      relative path from some "current" directory.</para>
1861      <para>After creating this library, the first step is to tell
1862      &CCL; to open the dynamic library.  This is done by calling
1863      .</para>
1864      <programlisting>
1865
1866Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
1867
1868? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
1869#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E&gt;
1870</programlisting>
1871      <para>You should use an absolute path here; using a relative
1872      one, such as just "libtypetest.dylib", would appear to work, but
1873      there are subtle problems which occur after reloading it.  See
1874      the Darwin notes on for details.  It would be a bad idea anyway,
1875      because software should never rely on its starting directory
1876      being anything in particular.</para>
1877      <para>This command returns a reference to the opened shared library, and
1878&CCL; also adds one to the global variable
1879<literal>ccl::*shared-libraries*</literal>:</para>
1880      <programlisting>
1881
1882? ccl::*shared-libraries*
1883(#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
1884 #&lt;SHLIB /usr/lib/libSystem.B.dylib #x606179E>)
1885      </programlisting>
1886      <para>Before we call anything, let's check that the individual
1887      functions can actually be found by the system.  We don't have to
1888      do this, but it helps to know how to find out whether this is
1889      the problem, when something goes wrong.  We use <xref
1890      linkend="m_external-call"/>:</para>
1891      <programlisting>
1892
1893? (external "_void_void_test")
1894#&lt;EXTERNAL-ENTRY-POINT "_void_void_test" (#x000CFDF8) /Users/andewl/openmcl/libtypetest.dylib #x638EDF6>
1895
1896? (external "_sc_sc_test")
1897#&lt;EXTERNAL-ENTRY-POINT "_sc_sc_test" (#x000CFE50) /Users/andewl/openmcl/libtypetest.dylib #x638EB3E>
1898
1899? (external "_uc_uc_test")
1900#&lt;EXTERNAL-ENTRY-POINT "_uc_uc_test" (#x000CFED4) /Users/andewl/openmcl/libtypetest.dylib #x638E626>
1901      </programlisting>
1902      <para>Notice that the actual function names have been "mangled"
1903      by the C linker.  The first function was named "void_void_test"
1904      in typetest.c, but in libtypetest.dylib, it has an underscore (a
1905      "_" symbol) before it: "_void_void_test".  So, this is the name
1906      which you have to use.  The mangling - the way the name is
1907      changed - may be different for other operating systems or other
1908      versions, so you need to "just know" how it's done...</para>
1909      <para>Also, pay particular attention to the fact that a
1910      hexadecimal value appears in the EXTERNAL-ENTRY-POINT.
1911      (#x000CFDF8, for example - but what it is doesn't matter.)
1912      These hex numbers mean that the function can be dereferenced.
1913      Functions which aren't found will not have a hex number.  For
1914      example:</para>
1915      <programlisting>
1916
1917? (external "functiondoesnotexist")
1918#&lt;EXTERNAL-ENTRY-POINT "functiondoesnotexist" {unresolved}  #x638E3F6>
1919</programlisting>
1920      <para>The "unresolved" tells us that &CCL; wasn't able to find this
1921      function, which means you would get an error, "Can't resolve foreign
1922      symbol," if you tried to call it.</para>
1923      <para>These external function references also are stored in a
1924      hash table which is accessible through a global variable,
1925      <literal>ccl::*eeps*</literal>.</para>
1926      <para>At this point, we are ready to try our first external
1927      function call:</para>
1928      <programlisting>
1929
1930? (external-call "_void_void_test" :void)
1931Entered void_void_test:
1932Exited  void_void_test:
1933NIL
1934      </programlisting>
1935      <para>We used , which is is the normal mechanism for accessing
1936      externally linked code.  The "_void_void_test" is the mangled
1937      name of the external function.  The :void refers to the return
1938      type of the function.</para>
1939      <para>The next step is to try passing a value to C, and getting one
1940back:</para>
1941      <programlisting>
1942
1943? (external-call "_sc_sc_test" :signed-byte -128 :signed-byte)
1944Entered sc_sc_test:
1945Data In: -128
1946Exited  sc_sc_test:
1947-128
1948</programlisting>
1949      <para>The first :signed-byte gives the type of the first
1950      argument, and then -128 gives the value to pass for it.  The
1951      second :signed-byte gives the return type.  The return type is
1952      always given by the last argument to .</para>
1953      <para>Everything looks good.  Now, let's try a number outside
1954      the range which fits in one byte:</para>
1955      <programlisting>
1956
1957? (external-call "_sc_sc_test" :signed-byte -567 :signed-byte)
1958Entered sc_sc_test:
1959Data In: -55
1960Exited  sc_sc_test:
1961-55
1962</programlisting>
1963      <para>Hmmmm.  A little odd.  Let's look at the unsigned stuff to
1964      see how it reacts:</para>
1965      <programlisting>
1966
1967? (external-call "_uc_uc_test" :unsigned-byte 255 :unsigned-byte)
1968Entered uc_uc_test:
1969Data In: 255
1970Exited  uc_uc_test:
1971255
1972</programlisting>
1973      <para>That looks okay.  Now, let's go outside the valid range again:</para>
1974      <programlisting>
1975
1976? (external-call "_uc_uc_test" :unsigned-byte 567 :unsigned-byte)
1977Entered uc_uc_test:
1978Data In: 55
1979Exited  uc_uc_test:
198055
1981
1982? (external-call "_uc_uc_test" :unsigned-byte -567 :unsigned-byte)
1983Entered uc_uc_test:
1984Data In: 201
1985Exited  uc_uc_test:
1986201
1987      </programlisting>
1988      <para>Since a signed byte can only hold values from -128 through 127, and
1989      an unsigned one can only hold values from 0 through 255, any number
1990      outside that range gets "clipped": only the low eight bits of it
1991      are used.</para>
1992      <para>What is important to remember is that <emphasis>external
1993      function calls have
1994      very few safety checks.</emphasis>
1995      Data outside the valid range for its type will silently do
1996      very strange things; pointers outside the valid range can very well
1997      crash the system.</para>
1998      <para>That's it for our first example library.  If you're still
1999      following along, let's add some more C code to look at the rest
2000      of the primitive types.  Then we'll need to recompile the
2001      dynamic library, load it again, and then we can see what
2002      happens.</para>
2003      <para>Add the following code to typetest.c:</para>
2004      <programlisting>
2005
2006int
2007si_si_test(int data)
2008{
2009    printf("Entered %s:\n", __FUNCTION__);
2010    printf("Data In: %d\n", data);
2011    printf("Exited  %s:\n", __FUNCTION__);
2012    fflush(stdout);
2013    return data;
2014}
2015
2016long
2017sl_sl_test(long data)
2018{
2019    printf("Entered %s:\n", __FUNCTION__);
2020    printf("Data In: %ld\n", data);
2021    printf("Exited  %s:\n", __FUNCTION__);
2022    fflush(stdout);
2023    return data;
2024}
2025
2026long long
2027sll_sll_test(long long data)
2028{
2029    printf("Entered %s:\n", __FUNCTION__);
2030    printf("Data In: %lld\n", data);
2031    printf("Exited  %s:\n", __FUNCTION__);
2032    fflush(stdout);
2033    return data;
2034}
2035
2036float
2037f_f_test(float data)
2038{
2039    printf("Entered %s:\n", __FUNCTION__);
2040    printf("Data In: %e\n", data);
2041    printf("Exited  %s:\n", __FUNCTION__);
2042    fflush(stdout);
2043    return data;
2044}
2045
2046double
2047d_d_test(double data)
2048{
2049    printf("Entered %s:\n", __FUNCTION__);
2050    printf("Data In: %e\n", data);
2051    printf("Exited  %s:\n", __FUNCTION__);
2052    fflush(stdout);
2053    return data;
2054}
2055</programlisting>
2056      <para>The command line to compile the dynamic library is the same as before:</para>
2057      <programlisting>
2058
2059gcc -dynamiclib -Wall -o libtypetest.dylib typetest.c \
2060    -install_name ./libtypetest.dylib
2061</programlisting>
2062      <para>Now, restart &CCL;.  This step is required because
2063      &CCL; cannot close and reload a dynamic library on OS
2064      X.</para>
2065      <para>Have you restarted?  Okay, try out the new code:</para>
2066      <programlisting>
2067
2068Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
2069
2070? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
2071#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
2072
2073? (external-call "_si_si_test" :signed-fullword -178965 :signed-fullword)
2074Entered si_si_test:
2075Data In: -178965
2076Exited  si_si_test:
2077-178965
2078
2079? ;; long is the same size as int on 32-bit machines.
2080(external-call "_sl_sl_test" :signed-fullword -178965 :signed-fullword)
2081Entered sl_sl_test:
2082Data In: -178965
2083Exited  sl_sl_test:
2084-178965
2085
2086? (external-call "_sll_sll_test"
2087                 :signed-doubleword -973891578912 :signed-doubleword)
2088Entered sll_sll_test:
2089Data In: -973891578912
2090Exited  sll_sll_test:
2091-973891578912
2092</programlisting>
2093      <para>Okay, everything seems to be acting as expected.  However,
2094      just to remind you that most of this stuff has no safety net,
2095      here's what happens if somebody mistakes
2096      <literal>sl_sl_test()</literal> for
2097      <literal>sll_sll_test()</literal>, thinking that a long is
2098      actually a doubleword:</para>
2099      <programlisting>
2100
2101? (external-call "_sl_sl_test"
2102                 :signed-doubleword -973891578912 :signed-doubleword)
2103Entered sl_sl_test:
2104Data In: -227
2105Exited  sl_sl_test:
2106-974957576192
2107      </programlisting>
2108      <para>Ouch.  The C function changes the value with no warning
2109      that something is wrong.  Even worse, it manages to pass the
2110      original value back to &CCL;, which hides the fact that
2111      something is wrong.</para>
2112      <para>Finally, let's take a look at doing this with
2113      floating-point numbers.</para>
2114      <programlisting>
2115
2116Welcome to &CCL; Version (Beta: Darwin) 0.14.2-040506!
2117
2118? (open-shared-library "/Users/andewl/openmcl/libtypetest.dylib")
2119#&lt;SHLIB /Users/andewl/openmcl/libtypetest.dylib #x638EF3E>
2120
2121? (external-call "_f_f_test" :single-float -1.256791e+11 :single-float)
2122Entered f_f_test:
2123Data In: -1.256791e+11
2124Exited  f_f_test:
2125-1.256791E+11
2126
2127? (external-call "_d_d_test" :double-float -1.256791d+290 :double-float)
2128Entered d_d_test:
2129Data In: -1.256791e+290
2130Exited  d_d_test:
2131-1.256791D+290
2132      </programlisting>
2133      <para>Notice that the number ends with "...e+11" for the single-float,
2134and "...d+290" for the
2135double-float.  Lisp has both of these float types itself, and the
2136d instead of the e is how you specify which to create.  If
2137you tried to pass :double-float 1.0e2 to external-call, Lisp would
2138be nice enough to notice and give you a type error.  Don't get the
2139:double-float wrong, though, because then there's no protection.</para>
2140      <para>Congratulations!  You now know how to call external C functions from
2141within &CCL;, and pass numbers back and forth.  Now that the basic
2142mechanics of calling and passing work, the next step is to examine how
2143to pass more complex data structures around.</para>
2144
2145      <sect2 id="Acknowledgement">
2146        <title>Acknowledgement</title>
2147        <para>This chapter was generously contributed by Andrew
2148        P. Lentvorski Jr.</para>
2149      </sect2>
2150    </sect1>
2151
2152    <sect1 id="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap">
2153      <title>Tutorial: Allocating Foreign Data on the Lisp Heap </title>
2154      <para>Not every foreign function is so marvelously easy to use
2155      as the ones we saw in the last section.  Some of them require
2156      you to allocate a C struct, fill it in with your own
2157      information, and pass it a pointer to the struct.  Some of them
2158      require you to allocate an empty struct so they can fill it in,
2159      and then you can read the information out of it.</para>
2160      <para>Also, some of them have their own structs and return a
2161      pointer to that same struct every time you call them, but those
2162      are easier to deal with, so they won't be covered in this
2163      section.</para>
2164      <para>You might know that Lisp (and, indeed, most programming
2165      languages) has two separate regions of memory.  There's the
2166      stack, which is where variable bindings are kept.  Memory on the
2167      stack is allocated every time any function is called, and
2168      deallocated when it returns, so it's useful for anything that
2169      doesn't need to last longer than one function call, when there's
2170      only one thread.  If that's all you need, you can do it with
2171      .</para>
2172      <para>Then, there's the heap, which holds everything else, and
2173      is our subject here.  There are two advantages and one big
2174      disadvantage to putting things on the heap rather than the
2175      stack.  First, data allocated on the heap can be passed outside
2176      of the scope in which it was created.  This is useful for data
2177      which may need to be passed between multiple C calls or multiple
2178      threads. Also, some data may be too large to copy multiple times
2179      or may be too large to allocate on the stack.</para>
2180      <para>The second advantage is security.  If incoming data is
2181      being placed directly onto the stack, the input data can cause
2182      stack overflows and underflows.  This is not something which
2183      Lisp users generally worry about since garbage collection
2184      generally handles memory management.  However, "stack smashing"
2185      is one of the classic exploits in C which malicious hackers can
2186      use to gain control of a machine.  Not checking external data is
2187      always a bad idea; however, allocating it into the heap at least
2188      offers more protection than direct stack allocation.</para>
2189      <para>The big disadvantage to allocating data on the heap is
2190      that it must be explicitly deallocated - you need to "free" it
2191      when you're done with it.  Ordinarily, in Lisp, you wouldn't
2192      allocate memory yourself, and the garbage collector would know
2193      about it, so you wouldn't have to think about it again.  When
2194      you're doing it manually, it's very different.  Memory
2195      management becomes a manual process, just like in C and
2196      C++.</para>
2197      <para>What that means is that, if you allocate something and
2198      then lose track of the pointer to it, there's no way to ever
2199      free that memory.  That's what's called a memory leak, and if
2200      your program leaks enough memory it will eventually use up all
2201      of it!  So, you need to be careful to not lose your
2202      pointers.</para>
2203      <para>That disadvantage, though, is also an advantage for using
2204      foreign functions.  Since the garbage collector doesn't know
2205      about this memory, it will never move it around.  External C
2206      code needs this, because it doesn't know how to follow it to
2207      where it moved, the way that Lisp code does.  If you allocate
2208      data manually, you can pass it to foreign code and know that no
2209      matter what that code needs to do with it, it will be able to,
2210      until you deallocated it.  Of course, you'd better be sure it's
2211      done before you do.  Otherwise, your program will be unstable
2212      and might crash sometime in the future, and you'll have trouble
2213      figuring out what caused the trouble, because there won't be
2214      anything pointing back and saying "you deallocated this too
2215      soon."</para>
2216      <para>And, so, on to the code...</para>
2217      <para>As in the last tutorial, our first step
2218      is to create a local dynamic library in order to help show
2219      what is actually going on between &CCL; and C.  So, create the file
2220      ptrtest.c, with the following code:</para>
2221      <programlisting>
2222#include &lt;stdio.h&gt;
2223
2224void reverse_int_array(int * data, unsigned int dataobjs)
2225{
2226  int i, t;
2227
2228  for(i=0; i&lt;dataobjs/2; i++)
2229    {
2230      t = *(data+i);
2231      *(data+i) = *(data+dataobjs-1-i);
2232      *(data+dataobjs-1-i) = t;
2233    }
2234}
2235
2236void reverse_int_ptr_array(int **ptrs, unsigned int ptrobjs)
2237{
2238  int *t;
2239  int i;
2240
2241  for(i=0; i&lt;ptrobjs/2; i++)
2242    {
2243      t = *(ptrs+i);
2244      *(ptrs+i) = *(ptrs+ptrobjs-1-i);
2245      *(ptrs+ptrobjs-1-i) = t;
2246    }
2247}
2248
2249void
2250reverse_int_ptr_ptrtest(int **ptrs)
2251{
2252  reverse_int_ptr_array(ptrs, 2);
2253
2254  reverse_int_array(*(ptrs+0), 4);
2255  reverse_int_array(*(ptrs+1), 4);
2256}
2257      </programlisting>
2258      <para>This defines three functions.
2259      <literal>reverse_int_array</literal> takes a pointer to an array
2260      of <literal>int</literal>s, and a count telling how many items
2261      are in the array, and loops through it putting the elements in
2262      reverse.  <literal>reverse_int_ptr_array</literal> does the same
2263      thing, but with an array of pointers to <literal>int</literal>s.
2264      It only reverses the order the pointers are in; each pointer
2265      still points to the same thing.
2266      <literal>reverse_int_ptr_ptrtest</literal> takes an array of
2267      pointers to arrays of <literal>int</literal>s.  (With me?)  It
2268      doesn't need to be told their sizes; it just assumes that the
2269      array of pointers has two items, and that both of those are
2270      arrays which have four items.  It reverses the array of
2271      pointers, then it reverses each of the two arrays of
2272      <literal>int</literal>s.</para>
2273      <para>Now, compile ptrtest.c into a dynamic library using the
2274      command:</para>
2275      <programlisting>
2276gcc -dynamiclib -Wall -o libptrtest.dylib ptrtest.c -install_name ./libptrtest.dylib
2277      </programlisting>
2278      <para>If that command doesn't make sense to you, feel free to go back
2279and read about it at .</para>
2280      <para>Now, start &CCL; and enter:</para>
2281      <programlisting>
2282? ;; make-heap-ivector courtesy of Gary Byers
2283(defun make-heap-ivector (element-count element-type)
2284  (let* ((subtag (ccl::element-type-subtype element-type)))
2285    (unless (= (logand subtag target::fulltagmask)
2286               target::fulltag-immheader)
2287      (error "~s is not an ivector subtype." element-type))
2288    (let* ((size-in-bytes (ccl::subtag-bytes subtag element-count)))
2289      (ccl::%make-heap-ivector subtag size-in-bytes element-count))))
2290MAKE-HEAP-IVECTOR
2291
2292? ;; dispose-heap-ivector created for symmetry
2293(defmacro dispose-heap-ivector (a mp)
2294  `(progn
2295     (ccl::%dispose-heap-ivector ,a)
2296     ;; Demolish the arguments for safety
2297     (setf ,a nil)
2298     (setf ,mp nil)))
2299DISPOSE-HEAP-IVECTOR
2300</programlisting>
2301      <para>If you don't understand how those functions do what they do.
2302      That's okay; it gets into very fine detail which really doesn't
2303      matter, because you don't need to change them.</para>
2304      <para>The function <literal>make-heap-ivector</literal> is the
2305      primary tool for allocating objects in heap memory.  It
2306      allocates a fixed-size &CCL; object in heap memory.  It
2307      returns both an array reference, which can be used directly from
2308      &CCL;, and a <literal>macptr</literal>, which can be used to
2309      access the underlying memory directly.  For example:</para>
2310      <programlisting>
2311? ;; Create an array of 3 4-byte-long integers
2312(multiple-value-bind (la lap)
2313    (make-heap-ivector 3 '(unsigned-byte 32))
2314  (setq a la)
2315  (setq ap lap))
2316;Compiler warnings :
2317;   Undeclared free variable A, in an anonymous lambda form.
2318;   Undeclared free variable AP, in an anonymous lambda form.
2319#&lt;A Mac Pointer #x10217C>
2320
2321? a
2322#(1396 2578 97862649)
2323
2324? ap
2325#&lt;A Mac Pointer #x10217C>
2326</programlisting>
2327      <para>It's important to realize that the contents of the
2328      <literal>ivector</literal> we've just created haven't been
2329      initialized, so their values are unpredictable, and you should
2330      be sure not to read from them before you set them, to avoid
2331      confusing results.</para>
2332      <para>At this point, <literal>a</literal> references an object
2333      which works just like a normal array.  You can refer to any item
2334      of it with the standard <literal>aref</literal> function, and
2335      set them by combining that with <literal>setf</literal>.  As
2336      noted above, the <literal>ivector</literal>'s contents haven't
2337      been initialized, so that's the next order of business:</para>
2338      <programlisting>
2339? a
2340#(1396 2578 97862649)
2341
2342? (aref a 2)
234397862649
2344
2345? (setf (aref a 0) 3)
23463
2347
2348? (setf (aref a 1) 4)
23494
2350
2351? (setf (aref a 2) 5)
23525
2353
2354? a
2355#(3 4 5)
2356</programlisting>
2357      <para>In addition, the <literal>macptr</literal> allows direct
2358      access to the same memory:</para>
2359      <programlisting>
2360? (setq *byte-length-of-long* 4)
23614
2362
2363? (%get-signed-long ap (* 2 *byte-length-of-long*))
23645
2365
2366? (%get-signed-long ap (* 0 *byte-length-of-long*))
23673
2368
2369? (setf (%get-signed-long ap (* 0 *byte-length-of-long*)) 6)
23706
2371
2372? (setf (%get-signed-long ap (* 2 *byte-length-of-long*)) 7)
23737
2374
2375? ;; Show that a actually got changed through ap
2376a
2377#(6 4 7)
2378      </programlisting>
2379      <para>So far, there is nothing about this object that could not
2380      be done much better with standard Lisp.  However, the
2381      <literal>macptr</literal> can be used to pass this chunk of
2382      memory off to a C function.  Let's use the C code to reverse the
2383      elements in the array:</para>
2384      <programlisting>
2385? ;; Insert the full path to your copy of libptrtest.dylib
2386(open-shared-library "/Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib")
2387#&lt;SHLIB /Users/andrewl/openmcl/openmcl/gtk/libptrtest.dylib #x639D1E6>
2388
2389? a
2390#(6 4 7)
2391
2392? ap
2393#&lt;A Mac Pointer #x10217C>
2394
2395? (external-call "_reverse_int_array" :address ap :unsigned-int (length a) :address)
2396#&lt;A Mac Pointer #x10217C>
2397
2398? a
2399#(7 4 6)
2400
2401? ap
2402#&lt;A Mac Pointer #x10217C>
2403</programlisting>
2404      <para>The array gets passed correctly to the C function,
2405      <literal>reverse_int_array</literal>.  The C function reverses
2406      the contents of the array in-place; that is, it doesn't make a
2407      new array, just keeps the same one and reverses what's in it.
2408      Finally, the C function passes control back to &CCL;.  Since
2409      the allocated array memory has been directly modifed, &CCL;
2410      reflects those changes directly in the array as well.</para>
2411      <para>There is one final bit of housekeeping to deal with.
2412      Before moving on, the memory needs to be deallocated:</para>
2413      <programlisting>
2414? ;; dispose-heap-ivector created for symmetry
2415;; Macro repeated here for pedagogy
2416(defmacro dispose-heap-ivector (a mp)
2417  `(progn
2418     (ccl::%dispose-heap-ivector ,a)
2419     ;; Demolish the arguments for safety
2420     (setf ,a nil)
2421     (setf ,mp nil)))
2422DISPOSE-HEAP-IVECTOR
2423
2424? (dispose-heap-ivector a ap)
2425NIL
2426
2427? a
2428NIL
2429
2430? ap
2431NIL
2432</programlisting>
2433      <para>The <literal>dispose-heap-ivector</literal> macro actually
2434      deallocates the ivector, releasing its memory into the heap for
2435      something else to use.  In addition, it makes sure that the
2436      variables which it was called with are set to nil, because
2437      otherwise they would still be referencing the memory of the
2438      ivector - which is no longer allocated, so that would be a bug.
2439      Making sure there are no other variables set to it is up to
2440      you.</para>
2441      <para>When do you call <literal>dispose-heap-ivector</literal>?
2442      Anytime after you know the ivector will never be used again, but
2443      no sooner.  If you have a lot of ivectors, say, in a hash table,
2444      you need to make sure that when whatever you were doing with the
2445      hash table is done, those ivectors all get freed.  Unless
2446      there's still something somewhere else which refers to them, of
2447      course!  Exactly what strategy to take depends on the situation,
2448      so just try to keep things simple unless you know better.</para>
2449      <para>The simplest situation is when you have things set up so
2450      that a Lisp object "encapsulates" a pointer to foreign data,
2451      taking care of all the details of using it.  In this case, you
2452      don't want those two things to have different lifetimes: You
2453      want to make sure your Lisp object exists as long as the foreign
2454      data does, and no longer; and you want to make sure the foreign
2455      data doesn't get deallocated while your Lisp object still refers
2456      to it.</para>
2457      <para>If you're willing to accept a few limitations, you can
2458      make this easy.  First, you can't let foreign code keep a
2459      permanent pointer to the memory; it has to always finish what
2460      it's doing, then return, and not refer to that memory again.
2461      Second, you can't let any Lisp code that isn't part of your
2462      encapsulating "wrapper" refer to the pointer directly.  Third,
2463      nothing, either foreign code or Lisp code, should explicitly
2464      deallocate the memory.</para>
2465      <para>If you can make sure all of these are true, you can at
2466      least ensure that the foreign pointer is deallocated when the
2467      encapsulating object is about to become garbage, by using
2468      &CCL;'s nonstandard "termination" mechanism, which is
2469      essentially the same as what Java and other languages call
2470      "finialization".</para>
2471      <para>Termination is a way of asking the garbage collector to
2472      let you know when it's about to destroy an object which isn't
2473      used anymore.  Before destroying the object, it calls a function
2474      which you write, called a terminator.</para>
2475      <para>So, you can use termination to find out when a particular
2476      <literal>macptr</literal> is about to become garbage.  That's
2477      not quite as helpful as it might seem: It's not exactly the same
2478      thing as knowing that the block of memory it points to is
2479      unreferenced.  For example, there could be another
2480      <literal>macptr</literal> somewhere to the same block; or, if
2481      it's a struct, there could be a <literal>macptr</literal> to one
2482      of its fields.  Most problematically, if the address of that
2483      memory has been passed to foreign code, it's sometimes hard to
2484      know whether that code has kept the pointer.  Most foreign
2485      functions don't, but it's not hard to think of
2486      exceptions.</para>
2487      <para>You can use code such as this to make all this happen:</para>
2488      <programlisting>
2489(defclass wrapper (whatever)
2490  ((element-type :initarg :element-type)
2491   (element-count :initarg :element-count)
2492   (ivector)
2493   (macptr)))
2494
2495(defmethod initialize-instance ((wrapper wrapper) &amp;rest initargs)
2496  (declare (ignore initargs))
2497  (call-next-method)
2498  (ccl:terminate-when-unreachable wrapper)
2499  (with-slots (ivector macptr element-type element-count) wrapper
2500    (multiple-value-bind (new-ivector new-macptr)
2501        (make-heap-ivector element-count element-type)
2502      (setq ivector new-ivector
2503            macptr new-macptr))))
2504
2505(defmethod ccl:terminate ((wrapper wrapper))
2506  (with-slots (ivector macptr) wrapper
2507    (when ivector
2508      (dispose-heap-ivector ivector macptr)
2509      (setq ivector nil
2510            macptr nil))))
2511      </programlisting>
2512      <para>The <literal>ccl:terminate</literal> method will be called
2513      on some arbitrary thread sometime (hopefully soon) after the GC
2514      has decided that there are no strong references to an object
2515      which has been the argument of a
2516      <literal>ccl:terminate-when-unreachable</literal> call.</para>
2517      <para>If it makes sense to say that the foreign object should
2518      live as long as there's Lisp code that references it (through
2519      the encapsulating obect) and no longer, this is one way of doing
2520      that.</para>
2521      <para>Now we've covered passing basic types back and forth with
2522      C, and we've done the same with pointers.  You may think this is
2523      all...  but we've only done pointers to basic types.  Join us
2524      next time for pointers... to pointers.</para>
2525
2526      <sect2 id="Acknowledgement--1-">
2527        <title>Acknowledgement</title>
2528        <para>Much of this chapter was generously contributed by
2529        Andrew P. Lentvorski Jr.</para>
2530      </sect2>
2531    </sect1>
2532
2533    <sect1>
2534      <title>The Foreign-Function-Interface Dictionary</title>
2535       
2536      <refentry id="m_def-foreign-type">
2537        <indexterm zone="m_def-foreign-type">
2538          <primary>def-foreign-type</primary>
2539        </indexterm>
2540
2541        <refnamediv>
2542          <refname>DEF-FOREIGN-TYPE</refname>
2543          <refpurpose></refpurpose>
2544          <refclass>Macro</refclass>
2545        </refnamediv>
2546
2547        <refsynopsisdiv>
2548          <synopsis>
2549            <function>def-foreign-type</function> name foreign-type-spec
2550          </synopsis>
2551        </refsynopsisdiv>
2552
2553        <refsect1>
2554          <title>Values</title>
2555
2556          <variablelist>
2557            <varlistentry>
2558              <term>name</term>
2559             
2560              <listitem>
2561                <para>NIL or a keyword; the keyword may contain
2562                <link linkend="Case-sensitivity-of-foreign-names-in-&CCL;" >escaping constructs</link>.</para>
2563              </listitem>
2564            </varlistentry>
2565           
2566            <varlistentry>
2567              <term>foreign-type-spec</term>
2568             
2569              <listitem>
2570                <para>A foreign type specifier, whose syntax is (loosely)
2571                defined above.</para>
2572              </listitem>
2573            </varlistentry>
2574          </variablelist>
2575        </refsect1>
2576
2577        <refsect1>
2578          <title>Description</title>
2579
2580          <para>If name is non-NIL, defines name to be an alias for the
2581          foreign type specified by foreign-type-spec. If foreign-type-spec
2582          is a named structure or union type, additionally defines that
2583          structure or union type.</para>
2584         
2585          <para>If name is NIL, foreign-type-spec must be a named foreign
2586          struct or union definition, in which case the foreign structure
2587          or
2588          union definition is put in effect.</para>
2589         
2590          <para>Note that there are two separate namespaces for foreign
2591          type names, one for the names of ordinary types and one for
2592          the names of structs and unions.  Which one
2593          <varname>name</varname> refers to depends on
2594          <varname>foreign-type-spec</varname> in the obvious manner.
2595          </para>
2596        </refsect1>
2597      </refentry>
2598
2599      <refentry id="m_make-record">
2600        <indexterm zone="m_make-record">
2601          <primary>make-record</primary>
2602        </indexterm>
2603
2604        <refnamediv>
2605          <refname>MAKE-RECORD</refname>
2606          <refpurpose></refpurpose>
2607          <refclass>Macro</refclass>
2608        </refnamediv>
2609
2610        <refsynopsisdiv>
2611          <synopsis>
2612            <function>make-record</function> typespec
2613            &rest; initforms => result
2614          </synopsis>
2615        </refsynopsisdiv>
2616
2617        <refsect1>
2618          <title>Values</title>
2619
2620          <variablelist>
2621            <varlistentry>
2622              <term>typespec</term>
2623
2624              <listitem>
2625                <para>A foreign type specifier, or a keyword which is used
2626                as the name of a foreign struct or union.</para>
2627              </listitem>
2628            </varlistentry>
2629
2630            <varlistentry>
2631              <term>initforms</term>
2632
2633              <listitem>
2634                <para>If the type denoted by <varname>typespec</varname>
2635                is scalar, a single value appropriate for that type;
2636                otherwise, a list of alternating field names and
2637                values appropriate for the types of those fields.</para>
2638              </listitem>
2639            </varlistentry>
2640
2641            <varlistentry>
2642              <term>result</term>
2643
2644              <listitem>
2645                <para>
2646                  A <type>macptr</type> which encapsulates the address of a
2647                  newly-allocated record on the foreign heap.
2648                </para>
2649              </listitem>
2650            </varlistentry>
2651          </variablelist>
2652        </refsect1>
2653
2654        <refsect1>
2655          <title>Description</title>
2656
2657          <para>
2658            Expands into code which allocates and initalizes
2659            an instance of the type
2660            denoted by <varname>typespec</varname>, on the foreign
2661            heap.  The record is allocated using the C function
2662            <function>malloc</function>, and the user of
2663            <function>make-record</function> must explicitly call
2664            the C function <function>free</function> to deallocate the
2665            record, when it is no longer needed.
2666          </para>
2667
2668          <para>
2669            If <varname>initforms</varname> is provided, its value
2670            or values are used in the initialization.  When the type
2671            is a scalar, <varname>initforms</varname> is either a single
2672            value which can be coerced to that type, or no value, in which
2673            case binary 0 is used.  When the type is a <type>struct</type>,
2674            <varname>initforms</varname> is a list, giving field names
2675            and the values for each.  Each field is treated in the same way
2676            as a scalar is: If a value for it is given, it must be
2677            coerceable to the field's type; if not, binary 0 is used.
2678          </para>
2679
2680          <para>
2681            When the type is an array, <varname>initforms</varname> may
2682            not be provided, because <function>make-record</function>
2683            cannot initialize its values.  <function>make-record</function>
2684            is also unable to initialize fields of a <type>struct</type>
2685            which are themselves
2686            <type>struct</type>s.  The user of
2687            <function>make-record</function> should set these values
2688            by another means.
2689          </para>
2690
2691          <para>
2692            A possibly-significant limitation is that it must be possible to
2693            find the foreign type at the time the macro is expanded;
2694            <function>make-record</function> signals an error if this is
2695            not the case.
2696          </para>
2697        </refsect1>
2698
2699        <refsect1>
2700          <title>Notes</title>
2701
2702          <para>
2703            It is inconvenient that <function>make-record</function> is a
2704            macro, because this means that <varname>typespec</varname>
2705            cannot be a variable; it must be an immediate value.
2706          </para>
2707           
2708          <para>
2709            If it weren't for this requirement,
2710            <function>make-record</function> could be a function.  However,
2711            that would mean that any stand-alone application using it would
2712            have to include a copy of the interface database
2713            (see <xref linkend="The-Interface-Database"/>), which is undesireable
2714            because it's large.
2715          </para>
2716        </refsect1>
2717      </refentry>
2718
2719      <refentry id="m_rlet">
2720        <indexterm zone="m_rlet">
2721          <primary>rlet</primary>
2722        </indexterm>
2723
2724        <refnamediv>
2725          <refname>RLET</refname>
2726          <refpurpose></refpurpose>
2727          <refclass>Macro</refclass>
2728        </refnamediv>
2729
2730        <refsynopsisdiv>
2731          <synopsis>
2732            <function>rlet</function> (var typespec &rest; initforms)*
2733            &body; body
2734          </synopsis>
2735        </refsynopsisdiv>
2736
2737        <refsect1>
2738          <title>Values</title>
2739
2740          <variablelist>
2741            <varlistentry>
2742              <term>var</term>
2743
2744              <listitem>
2745                <para>A symbol (a lisp variable)</para>
2746              </listitem>
2747            </varlistentry>
2748
2749            <varlistentry>
2750              <term>typespec</term>
2751
2752              <listitem>
2753                <para>A foreign type specifier or foreign record name.</para>
2754              </listitem>
2755            </varlistentry>
2756
2757 <varlistentry>
2758              <term>initforms</term>
2759
2760              <listitem>
2761                <para>As described above, for
2762                <xref linkend="m_make-record"/></para>
2763              </listitem>
2764            </varlistentry>
2765          </variablelist>
2766        </refsect1>
2767
2768        <refsect1>
2769          <title>Description</title>
2770
2771          <para>Executes <varname>body</varname>
2772          in an environment in which each var is bound
2773          to <link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link> encapsulating the
2774          address of a stack-allocated foreign memory block, allocated and
2775          initialized from typespec and initforms as per
2776          <xref linkend="m_make-record"/>.
2777          Returns whatever value(s) <varname>body</varname>
2778          returns.</para>
2779         
2780          <para>Record fields that aren&#39;t explicitly initialized have
2781          unspecified contents.</para>
2782        </refsect1>
2783      </refentry>
2784
2785      <refentry id="m_rletz">
2786        <indexterm zone="m_rletz">
2787          <primary>rletz</primary>
2788        </indexterm>
2789
2790        <refnamediv>
2791          <refname>RLETZ</refname>
2792          <refpurpose></refpurpose>
2793          <refclass>Macro</refclass>
2794        </refnamediv>
2795
2796        <refsynopsisdiv>
2797          <synopsis>
2798            <function>rletz</function> (var typespec &rest; initforms)*
2799            &body; body
2800          </synopsis>
2801        </refsynopsisdiv>
2802
2803        <refsect1>
2804          <title>Values</title>
2805
2806          <variablelist>
2807            <varlistentry>
2808              <term>var</term>
2809
2810              <listitem>
2811                <para>A symbol (a lisp variable)</para>
2812              </listitem>
2813            </varlistentry>
2814
2815            <varlistentry>
2816              <term>typespec</term>
2817
2818              <listitem>
2819                <para>A foreign type specifier or foreign record name.</para>
2820              </listitem>
2821            </varlistentry>
2822
2823            <varlistentry>
2824              <term>initforms</term>
2825
2826              <listitem>
2827                <para>As described above, for ccl:make-record</para>
2828              </listitem>
2829            </varlistentry>
2830          </variablelist>
2831        </refsect1>
2832
2833        <refsect1>
2834          <title>Description</title>
2835
2836          <para>Executes body in an environment in which each var is
2837          bound to <link
2838          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
2839          MACPTR</link> encapuslating the address of a stack-allocated
2840          foreign memory block, allocated and initialized from
2841          typespec and initforms as ccl:make-record.</para>
2842         
2843          <para>Returns whatever value(s) body returns.</para>
2844
2845          <para>Unlike rlet, record fields that aren&#39;t explicitly
2846          initialized are set to binary 0.</para>
2847        </refsect1>
2848      </refentry>
2849
2850      <refentry id="m_pref">
2851        <indexterm zone="m_pref">
2852          <primary>pref</primary>
2853        </indexterm>
2854
2855        <refnamediv>
2856          <refname>PREF</refname>
2857          <refpurpose></refpurpose>
2858          <refclass>Macro</refclass>
2859        </refnamediv>
2860
2861        <refsynopsisdiv>
2862          <synopsis>
2863            <function>pref</function> ptr accessor-form
2864          </synopsis>
2865
2866        </refsynopsisdiv>
2867
2868        <refsect1>
2869          <title>Values</title>
2870
2871          <variablelist>
2872            <varlistentry>
2873              <term>ptr</term>
2874
2875              <listitem>
2876                <para><link linkend="Referencing-and-Using-Foreign-Memory-Addresses">a MACPTR</link>.</para>
2877              </listitem>
2878            </varlistentry>
2879
2880            <varlistentry>
2881              <term>accessor-form</term>
2882
2883              <listitem>
2884                <para>a keyword which names a foreign type or record, as
2885                described in <xref linkend="Foreign-type--record--and-field-names"/>.
2886                </para>
2887              </listitem>
2888            </varlistentry>
2889          </variablelist>
2890        </refsect1>
2891
2892        <refsect1>
2893          <title>Description</title>
2894
2895          <para>References an instance of a foreign type (or a component of
2896          a foreign type) accessible via ptr.</para>
2897         
2898          <para>Expands into code which references the indicated scalar type
2899          or component, or returns a pointer to a composite type.</para>
2900         
2901          <para>PREF can be used with SETF.</para>
2902         
2903          <para>RREF is a deprecated alternative to PREF. It accepts a
2904          :STORAGE keyword and rather loudly ignores it.</para>
2905        </refsect1>
2906      </refentry>
2907
2908      <refentry id="f_open-shared-library">
2909        <indexterm zone="f_open-shared-library">
2910          <primary>open-shared-library</primary>
2911        </indexterm>
2912       
2913        <refnamediv>
2914          <refname>OPEN-SHARED-LIBRARY</refname>
2915          <refpurpose>Asks the operating system to load a shared library
2916          for &CCL; to use.</refpurpose>
2917          <refclass>Function</refclass>
2918        </refnamediv>
2919       
2920        <refsynopsisdiv>
2921          <synopsis>
2922            <function>open-shared-library</function> name => library
2923          </synopsis>
2924        </refsynopsisdiv>
2925       
2926        <refsect1>
2927          <title>Values</title>
2928         
2929          <variablelist>
2930            <varlistentry>
2931              <term>name</term> 
2932              <listitem>
2933                <para>A SIMPLE-STRING which is presumed to be the so-name of
2934                or a filesystem path to the library.</para>
2935              </listitem>
2936            </varlistentry>
2937           
2938            <varlistentry>
2939              <term>library</term>
2940              <listitem>
2941                <para>An object of type SHLIB which describes the
2942                library denoted by <varname>name</varname>.</para>
2943              </listitem>
2944            </varlistentry>
2945          </variablelist>
2946        </refsect1>
2947       
2948        <refsect1>
2949          <title>Description</title>
2950
2951          <para>If the library denoted by <varname>name</varname> can
2952          be loaded by the
2953          operating system, returns an object of type SHLIB that describes
2954          the library; if the library is already open, increments a
2955          reference count. If the library can&#39;t be loaded, signals a
2956          SIMPLE-ERROR which contains an often-cryptic message from the
2957          operating system.</para>
2958        </refsect1>
2959
2960        <refsect1>
2961          <title>Examples</title>
2962
2963          <programlisting format="linespecific">;;; Try to do something simple.
2964? (open-shared-library &#34;libgtk.so&#34;)
2965&#62; Error: Error opening shared library &#34;libgtk.so&#34;: /usr/lib/libgtk.so: undefined symbol: gdk_threads_mutex
2966&#62; While executing: OPEN-SHARED-LIBRARY
2967
2968;;; Grovel around, curse, and try to find out where &#34;gdk_threads_mutex&#34;
2969;;; might be defined. Then try again:
2970
2971? (open-shared-library &#34;libgdk.so&#34;)
2972#&#60;SHLIB libgdk.so #x3046DBB6&#62;
2973
2974? (open-shared-library &#34;libgtk.so&#34;)
2975#&#60;SHLIB libgtk.so #x3046DC86&#62;
2976
2977;;; Reference an external symbol defined in one of those libraries.
2978
2979? (external &#34;gtk_main&#34;)
2980#&#60;EXTERNAL-ENTRY-POINT &#34;gtk_main&#34; (#x012C3004) libgtk.so #x3046FE46&#62;
2981
2982;;; Close those libraries.
2983
2984? (close-shared-library &#34;libgtk.so&#34;)
2985T
2986
2987? (close-shared-library &#34;libgdk.so&#34;)
2988T
2989
2990;;; Reference the external symbol again.
2991
2992? (external &#34;gtk_main&#34;)
2993#&#60;EXTERNAL-ENTRY-POINT &#34;gtk_main&#34; {unresolved} libgtk.so #x3046FE46&#62;</programlisting>
2994        </refsect1>
2995
2996        <refsect1>
2997          <title>Notes</title>
2998
2999          <para>It would be helpful to describe what an soname is and give
3000          examples of one.</para>
3001
3002          <para>Does the SHLIB still get returned if the library is
3003          already open?</para>
3004        </refsect1>
3005      </refentry>
3006
3007      <refentry id="f_close-shared-library">
3008        <indexterm zone="f_close-shared-library">
3009          <primary>close-shared-library</primary>
3010        </indexterm>
3011
3012        <refnamediv>
3013          <refname>CLOSE-SHARED-LIBRARY</refname>
3014          <refpurpose>Stops using a shared library, informing the operating
3015          system that it can be unloaded if appropriate.</refpurpose>
3016          <refclass>Function</refclass>
3017        </refnamediv>
3018
3019        <refsynopsisdiv>
3020          <synopsis>
3021            <function>close-shared-library</function> library &key;
3022          completely</synopsis>
3023        </refsynopsisdiv>
3024
3025        <refsect1>
3026          <title>Values</title>
3027
3028          <variablelist>
3029            <varlistentry>
3030              <term>library</term>
3031
3032              <listitem>
3033                <para>either an object of type SHLIB, or a string which
3034                designates one by its so-name.</para>
3035              </listitem>
3036            </varlistentry>
3037
3038            <varlistentry>
3039              <term>completely</term>
3040
3041              <listitem>
3042                <para>a boolean.  The default is T.</para>
3043              </listitem>
3044            </varlistentry>
3045          </variablelist>
3046        </refsect1>
3047
3048        <refsect1>
3049          <title>Description</title>
3050
3051          <para>If <varname>completely</varname> is T, sets the
3052          reference count of <varname>library</varname> to 0.  Otherwise,
3053          decrements it by 1.  In either case, if the reference count
3054          becomes 0, <function>close-shared-library</function>
3055          frees all memory resources consumed <varname>library</varname>
3056          and
3057          causes any EXTERNAL-ENTRY-POINTs known to be defined by it to
3058          become unresolved.</para>
3059        </refsect1>
3060      </refentry>
3061
3062      <refentry id="m_external">
3063        <indexterm zone="m_external">
3064          <primary>external</primary>
3065        </indexterm>
3066       
3067        <refnamediv>
3068          <refname>EXTERNAL</refname>
3069          <refpurpose>Resolves a reference to an external symbol which
3070          is defined in a shared library.</refpurpose>
3071          <refclass>Macro</refclass>
3072        </refnamediv>
3073
3074        <refsynopsisdiv>
3075          <synopsis>
3076            <function>external</function> name => entry
3077          </synopsis>
3078        </refsynopsisdiv>
3079
3080        <refsect1>
3081          <title>Values</title>
3082
3083          <variablelist>
3084            <varlistentry>
3085              <term>name</term>
3086              <listitem>
3087                <para>
3088                  a simple-string which names an external symbol.
3089                  Case-sensitive.
3090                </para>
3091              </listitem>
3092            </varlistentry>
3093            <varlistentry>
3094              <term>entry</term>
3095              <listitem>
3096                <para>
3097                  an object of type EXTERNAL-ENTRY-POINT which maintains
3098                  the address of the foreign symbol named by
3099                  <varname>name</varname>.
3100                </para>
3101              </listitem>
3102            </varlistentry>
3103          </variablelist>
3104        </refsect1>
3105
3106        <refsect1>
3107          <title>Description</title>
3108
3109          <para>If there is already an EXTERNAL-ENTRY-POINT for
3110          the symbol named by <varname>name</varname>, finds it and
3111          returns it.  If not, creates one and returns it.</para>
3112
3113          <para>Tries to resolve the entry point to a memory address,
3114          and identify the containing library.</para>
3115
3116          <para>Be aware that under Darwin, external functions which
3117          are callable from C have underscores prepended to their names,
3118          as in "_fopen".</para>
3119        </refsect1>
3120      </refentry>
3121
3122      <refentry id="f_Pff-call">
3123        <indexterm zone="f_Pff-call">
3124          <primary>%ff-call</primary>
3125        </indexterm>
3126
3127        <refnamediv>
3128          <refname>%FF-CALL</refname>
3129          <refpurpose></refpurpose>
3130          <refclass>Function</refclass>
3131        </refnamediv>
3132
3133        <refsynopsisdiv>
3134          <synopsis>
3135            <function>%ff-call</function> entrypoint
3136            {arg-type-keyword arg}* &optional; result-type-keyword
3137          </synopsis>
3138        </refsynopsisdiv>
3139
3140        <refsect1>
3141          <title>Values</title>
3142
3143          <variablelist>
3144            <varlistentry>
3145              <term>entrypoint</term>
3146             
3147              <listitem>
3148                <para>A fixnum or MACPTR</para>
3149              </listitem>
3150            </varlistentry>
3151
3152            <varlistentry>
3153              <term>arg-type-keyword</term>
3154
3155              <listitem>
3156                <para>One of the foreign argument-type keywords, described
3157                above</para>
3158              </listitem>
3159            </varlistentry>
3160
3161            <varlistentry>
3162              <term>arg</term>
3163
3164              <listitem>
3165                <para>A lisp value of type indicated by the corresponding
3166                arg-type-keyword</para>
3167              </listitem>
3168            </varlistentry>
3169
3170            <varlistentry>
3171              <term>result-type-keyword</term>
3172
3173              <listitem>
3174                <para>One of the foreign argument-type keywords, described
3175                above</para>
3176              </listitem>
3177            </varlistentry>
3178          </variablelist>
3179        </refsect1>
3180
3181        <refsect1>
3182          <title>Description</title>
3183
3184          <para>Calls the foreign function at address entrypoint passing the
3185          values of each arg as a foreign argument of type indicated by the
3186          corresponding arg-type-keyword. Returns the foreign function
3187          result (coerced to a Lisp object of type indicated by
3188          result-type-keyword), or NIL if result-type-keyword is :VOID or
3189          NIL</para>
3190        </refsect1>
3191      </refentry>
3192
3193      <refentry id="m_ff-call">
3194        <indexterm zone="m_ff-call">
3195          <primary>ff-call</primary>
3196        </indexterm>
3197
3198        <refnamediv>
3199          <refname>FF-CALL</refname>
3200          <refpurpose></refpurpose>
3201          <refclass>Macro</refclass>
3202        </refnamediv>
3203
3204        <refsynopsisdiv>
3205          <synopsis>
3206            <function>ff-call</function> entrypoint
3207            {arg-type-specifier arg}* &optional; result-type-specifier
3208          </synopsis>
3209        </refsynopsisdiv>
3210
3211        <refsect1>
3212          <title>Values</title>
3213
3214          <variablelist>
3215            <varlistentry>
3216              <term>entrypoint</term>
3217
3218              <listitem>
3219                <para>A fixnum or MACPTR</para>
3220              </listitem>
3221            </varlistentry>
3222
3223            <varlistentry>
3224              <term>arg-type-specifer</term>
3225
3226              <listitem>
3227                <para>One of the foreign argument-type keywords, described
3228                above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
3229                type specifier</link>.</para>
3230              </listitem>
3231            </varlistentry>
3232
3233            <varlistentry>
3234              <term>arg</term>
3235
3236              <listitem>
3237                <para>A lisp value of type indicated by the corresponding
3238                arg-type-specifier</para>
3239              </listitem>
3240            </varlistentry>
3241
3242            <varlistentry>
3243              <term>result-type-specifier</term>
3244
3245              <listitem>
3246                <para>One of the foreign argument-type keywords, described
3247                above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
3248                type specifier</link>.</para>
3249              </listitem>
3250            </varlistentry>
3251          </variablelist>
3252        </refsect1>
3253
3254        <refsect1>
3255          <title>Description</title>
3256
3257          <para>Calls the foreign function at address entrypoint passing the
3258          values of each arg as a foreign argument of type indicated by the
3259          corresponding arg-type-specifier. Returns the foreign function
3260          result (coerced to a Lisp object of type indicated by
3261          result-type-specifier), or NIL if result-type-specifer is :VOID or
3262          NIL</para>
3263        </refsect1>
3264      </refentry>
3265
3266      <refentry id="f_Preference-external-entry-point">
3267        <indexterm zone="f_Preference-external-entry-point">
3268          <primary>%reference-external-entry-point</primary>
3269        </indexterm>
3270
3271        <refnamediv>
3272          <refname>%REFERENCE-EXTERNAL-ENTRY-POINT</refname>
3273          <refpurpose></refpurpose>
3274          <refclass>Function</refclass>
3275        </refnamediv>
3276
3277        <refsynopsisdiv>
3278          <synopsis>
3279            <function>%reference-external-entry-point</function> eep
3280          </synopsis>
3281        </refsynopsisdiv>
3282
3283        <refsect1>
3284          <title>Values</title>
3285
3286          <variablelist>
3287            <varlistentry>
3288              <term>eep</term>
3289
3290              <listitem>
3291                <para>An EXTERNAL-ENTRY-POINT, as obtained by the EXTERNAL
3292                macro.</para>
3293              </listitem>
3294            </varlistentry>
3295          </variablelist>
3296        </refsect1>
3297
3298        <refsect1>
3299          <title>Description</title>
3300
3301          <para>Tries to resolve the address of the EXTERNAL-ENTRY-POINT
3302          eep; returns a fixnum representation of that address if
3303          successful, else signals an error.</para>
3304        </refsect1>
3305      </refentry>
3306
3307      <refentry id="m_external-call">
3308        <indexterm zone="m_external-call">
3309          <primary>external-call</primary>
3310        </indexterm>
3311
3312        <refnamediv>
3313          <refname>EXTERNAL-CALL</refname>
3314          <refpurpose></refpurpose>
3315          <refclass>Macro</refclass>
3316        </refnamediv>
3317
3318        <refsynopsisdiv>
3319          <synopsis>
3320            <function>external-call</function> name
3321            {arg-type-specifier arg}* &optional; result-type-specifier
3322          </synopsis>
3323        </refsynopsisdiv>
3324
3325        <refsect1>
3326          <title>Values</title>
3327
3328          <variablelist>
3329            <varlistentry>
3330              <term>name</term>
3331
3332              <listitem>
3333                <para>A lisp string. See external, above.</para>
3334              </listitem>
3335            </varlistentry>
3336
3337            <varlistentry>
3338              <term>arg-type-specifer</term>
3339
3340              <listitem>
3341                <para>One of the foreign argument-type keywords, described
3342                above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
3343                type specifier</link>.</para>
3344              </listitem>
3345            </varlistentry>
3346
3347            <varlistentry>
3348              <term>arg</term>
3349
3350              <listitem>
3351                <para>A lisp value of type indicated by the corresponding
3352                arg-type-specifier</para>
3353              </listitem>
3354            </varlistentry>
3355
3356            <varlistentry>
3357              <term>result-type-specifier</term>
3358
3359              <listitem>
3360                <para>One of the foreign argument-type keywords, described
3361                above, or an equivalent <link linkend="Specifying-And-Using-Foreign-Types">foreign
3362                type specifier</link>.</para>
3363              </listitem>
3364            </varlistentry>
3365          </variablelist>
3366        </refsect1>
3367
3368        <refsect1>
3369          <title>Description</title>
3370
3371          <para>Calls the foreign function at the address obtained by
3372          resolving the external-entry-point associated with name, passing
3373          the values of each arg as a foreign argument of type indicated by
3374          the corresponding arg-type-specifier. Returns the foreign function
3375          result (coerced to a Lisp object of type indicated by
3376          result-type-specifier), or NIL if result-type-specifer is :VOID or
3377          NIL</para>
3378        </refsect1>
3379      </refentry>
3380
3381      <refentry id="f_foreign-symbol-entry">
3382        <indexterm zone="f_foreign-symbol-entry">
3383          <primary>foreign-symbol-entry</primary>
3384        </indexterm>
3385
3386        <refnamediv>
3387          <refname>FOREIGN-SYMBOL-ENTRY</refname>
3388          <refpurpose></refpurpose>
3389          <refclass>Function</refclass>
3390        </refnamediv>
3391
3392        <refsynopsisdiv>
3393          <synopsis>
3394            <function>foreign-symbol-entry</function> name
3395          </synopsis>
3396        </refsynopsisdiv>
3397
3398        <refsect1>
3399          <title>Values</title>
3400
3401          <variablelist>
3402            <varlistentry>
3403              <term>name</term>
3404
3405              <listitem>
3406                <para>A lisp string.</para>
3407              </listitem>
3408            </varlistentry>
3409          </variablelist>
3410        </refsect1>
3411
3412        <refsect1>
3413          <title>Description</title>
3414
3415          <para>Tries to resolve the address of the foreign symbol name. If
3416          successful, returns a fixnum representation of that address, else
3417          returns NIL.</para>
3418        </refsect1>
3419      </refentry>
3420
3421      <refentry id="f_foreign-symbol-address">
3422        <indexterm zone="f_foreign-symbol-address">
3423          <primary>foreign-symbol-address</primary>
3424        </indexterm>
3425
3426        <refnamediv>
3427          <refname>FOREIGN-SYMBOL-ADDRESS</refname>
3428          <refpurpose></refpurpose>
3429          <refclass>Function</refclass>
3430        </refnamediv>
3431
3432        <refsynopsisdiv>
3433          <synopsis>
3434            <function>foreign-symbol-address</function> name
3435          </synopsis>
3436        </refsynopsisdiv>
3437
3438        <refsect1>
3439          <title>Values</title>
3440
3441          <variablelist>
3442            <varlistentry>
3443              <term>name</term>
3444
3445              <listitem>
3446                <para>A lisp string.</para>
3447              </listitem>
3448            </varlistentry>
3449          </variablelist>
3450        </refsect1>
3451
3452        <refsect1>
3453          <title>Description</title>
3454
3455          <para>Tries to resolve the address of the foreign symbol
3456          name. If successful, returns that address encapsulated in
3457          <link
3458          linkend="Referencing-and-Using-Foreign-Memory-Addresses">a
3459          MACPTR</link>, else returns NIL.</para>
3460        </refsect1>
3461      </refentry>
3462
3463      <refentry id="m_defcallback">
3464        <indexterm zone="m_defcallback">
3465          <primary>defcallback</primary>
3466        </indexterm>
3467
3468        <refnamediv>
3469          <refname>DEFCALLBACK</refname>
3470          <refpurpose></refpurpose>
3471          <refclass>Macro</refclass>
3472        </refnamediv>
3473
3474        <refsynopsisdiv>
3475          <synopsis>
3476            <function>defcallback</function> name
3477            ({arg-type-specifier var}* &optional; result-type-specifier)
3478            &body; body
3479          </synopsis>
3480        </refsynopsisdiv>
3481
3482        <refsect1>
3483          <title>Values</title>
3484
3485          <variablelist>
3486            <varlistentry>
3487              <term>name</term>
3488
3489              <listitem>
3490                <para>A symbol which can be made into a special variable</para>
3491              </listitem>
3492            </varlistentry>
3493
3494            <varlistentry>
3495              <term>arg-type-specifer</term>
3496
3497              <listitem>
3498                <para>One of the foreign argument-type keywords,
3499                described above, or an equivalent <link
3500                linkend="Specifying-And-Using-Foreign-Types">foreign
3501                type specifier</link>.  In addition, if the keyword
3502                :WITHOUT-INTERRUPTS is specified, the callback will be
3503                executed with lisp interrupts disabled if the
3504                corresponding var is non-NIL. If :WITHOUT-INTERRUPTS
3505                is specified more than once, the rightmost instance
3506                wins.</para>
3507              </listitem>
3508            </varlistentry>
3509
3510            <varlistentry>
3511              <term>var</term>
3512
3513              <listitem>
3514                <para>A symbol (lisp variable), which will be bound to a
3515                value of the specified type.</para>
3516              </listitem>
3517            </varlistentry>
3518
3519            <varlistentry>
3520              <term>body</term>
3521
3522              <listitem>
3523                <para>A sequence of lisp forms, which should return a value
3524                which can be coerced to the specified result-type.</para>
3525              </listitem>
3526            </varlistentry>
3527          </variablelist>
3528        </refsect1>
3529
3530        <refsect1>
3531          <title>Description</title>
3532
3533          <para>Proclaims <varname>name</varname>
3534          to be a special variable; sets its value to a
3535          MACPTR which, when called by foreign code, calls a lisp function
3536          which expects foreign arguments of the specified types and which
3537          returns a foreign value of the specified result type. Any argument
3538          variables which correspond to foreign arguments of type :ADDRESS
3539          are bound to stack-allocated MACPTRs.</para>
3540         
3541          <para>If <varname>name</varname>
3542          is already a callback function pointer, its value is
3543          not changed; instead, it&#39;s arranged
3544          that an
3545          updated version of the lisp callback function will be called.
3546          This feature allows for callback functions to be redefined
3547          incrementally, just like Lisp functions are.</para>
3548
3549          <para><function>defcallback</function>
3550          returns the callback pointer, e.g., the
3551          value of <varname>name</varname>.</para>
3552        </refsect1>
3553      </refentry>
3554
3555      <refentry id="rm_sharpsign-underscore">
3556        <indexterm zone="rm_sharpsign-underscore">
3557          <primary>#_</primary>
3558        </indexterm>
3559
3560        <refnamediv>
3561          <refname>#_</refname>
3562          <refpurpose></refpurpose>
3563          <refclass>Reader Macro</refclass>
3564        </refnamediv>
3565
3566        <refsect1>
3567          <title>Description</title>
3568
3569          <para>Reads a symbol from the current input stream, with *PACKAGE*
3570          bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
3571         
3572          <para>Does a lookup on that symbol in <link
3573          linkend="The-Interface-Database">the &CCL; interface
3574          database</link>, signalling an error if no foreign function
3575          information can be found for the symbol in any active <link
3576          linkend="Using-Interface-Directories">interface
3577          directory</link>.</para>
3578
3579          <para>Notes the foreign function information, including the foreign
3580          function&#39;s return type, the number and type of the foreign
3581          function&#39;s required arguments, and an indication of whether or
3582          not the function accepts additional arguments (via e.g., the
3583          &#34;varargs&#34; mechanism in C).</para>
3584
3585          <para>Defines a macroexpansion function on the symbol, which expand
3586          macro calls involving the symbol into EXTERNAL-CALL forms where
3587          foreign argument type specifiers for required arguments and the
3588          return value specifer are provided from the information ind the
3589          database.</para>
3590
3591          <para>Returns the symbol.</para>
3592
3593          <para>The effect of these steps is that it&#39;s possible to call
3594          foreign functions that take fixed numbers of arguments by simply
3595          providing argument values, as in:</para>
3596
3597          <programlisting format="linespecific">(#_isatty fd)
3598(#_read fd buf n)</programlisting>
3599
3600          <para>and to call foreign functions that take variable numbers of
3601          arguments by specifying the types of non-required args, as in:</para>
3602
3603          <programlisting format="linespecific">(with-cstrs ((format-string &#34;the answer is: %d&#34;))
3604  (#_printf format-string :int answer))</programlisting>
3605        </refsect1>
3606      </refentry>
3607
3608      <refentry id="rm_sharpsign-questionmark">
3609        <indexterm zone="rm_sharpsign-questionmark">
3610          <primary>#?</primary>
3611        </indexterm>
3612
3613        <refnamediv>
3614          <refname>#?</refname>
3615          <refpurpose></refpurpose>
3616          <refclass>Reader Macro</refclass>
3617        </refnamediv>
3618
3619        <refsect1>
3620          <title>Description</title>
3621
3622          <para>In &CCL; 0.14.2 and later, the #? reader macro can be used to
3623          access foreign variables; this functionality depends on the presence of
3624          &#34;vars.cdb&#34; files in the interface database. The current behavior
3625          of the #? reader macro is to:</para>
3626
3627          <para>Read a symbol from the current input stream, with *PACKAGE*
3628          bound to the &#34;OS&#34; package and with readtable-case preserved.</para>
3629         
3630          <para>Use that symbol&#39;s pname to access the &CCL; interface
3631          database, signalling an error if no appropriate foreign variable
3632          information can be found with that name in any active interface
3633          directory.</para>
3634
3635          <para>Use type information recorded in the database to construct a
3636          form which can be used to access the foreign variable, and return
3637          that form.</para>
3638
3639          <para>Please note that the set of foreign variables declared in header files
3640          may or may not match the set of foreign variables exported from
3641          libraries (we&#39;re generally talking about C and Unix here ...). When
3642          they do match, the form constructed by the #? reader macro manages the
3643          details of resolving and tracking changes to the foreign variable&#39;s
3644          address.</para>
3645
3646          <para>Future extensions (via prefix arguments to the reader macro) may
3647          offer additional behavior; it might be convenient (for instance) to be
3648          able to access the address of a foreign variable without dereferencing
3649          that address.</para>
3650
3651          <para>Foreign variables in C code tend to be platform- and
3652          packge-specific (the canonical example - &#34;errno&#34; - is typically
3653          not a variable when threads are involved. )</para>
3654
3655          <para>In LinuxPPC, </para>
3656
3657          <programlisting>? #?stderr</programlisting>
3658
3659          <para>returns a pointer to the stdio error stream (&#34;stderr&#34; is a
3660          macro under OSX/Darwin).</para>
3661
3662          <para>On both LinuxPPC and DarwinPPC, </para>
3663
3664          <programlisting>? #?sys_errlist</programlisting>
3665
3666          <para>returns a pointer to a C array of C error message strings.</para>
3667        </refsect1>
3668      </refentry>
3669
3670      <refentry id="f_use-interface-dir">
3671        <indexterm zone="f_use-interface-dir">
3672          <primary>use-interface-dir</primary>
3673        </indexterm>
3674
3675        <refnamediv>
3676          <refname>USE-INTERFACE-DIR</refname>
3677          <refpurpose></refpurpose>
3678          <refclass>Function</refclass>
3679        </refnamediv>
3680
3681        <refsynopsisdiv>
3682          <synopsis>
3683            <function>use-interface-dir</function> dir-id
3684          </synopsis>
3685        </refsynopsisdiv>
3686
3687        <refsect1>
3688          <title>Values</title>
3689
3690          <variablelist>
3691            <varlistentry>
3692              <term>dir-id</term>
3693
3694              <listitem>
3695                <para>A keyword whose pname, mapped to lower case, names a
3696                subdirectory of &#34;ccl:headers;&#34; (or
3697                "ccl:darwin-headers;")</para>
3698              </listitem>
3699            </varlistentry>
3700          </variablelist>
3701        </refsect1>
3702
3703        <refsect1>
3704          <title>Description</title>
3705
3706          <para>Tells &CCL; to add the interface directory denoted by
3707          dir-id to the list of interface directories which it consults for
3708          foreign type and function information. Arranges that that
3709          directory is searched before any others.</para>
3710
3711          <para>Note that <function>use-interface-dir</function>
3712          merely adds an entry
3713          to a search list.
3714          If the named directory doesn&#39;t exist in the file system
3715          or doesn&#39;t
3716          contain a set of database files, a runtime error may occur
3717          when &CCL;
3718          tries to open some database file in that directory, and it
3719          will try to
3720          open such a database file whenever it needs to find any
3721          foreign type or
3722          function information. <xref linkend="f_unuse-interface-dir"/>
3723          may come in
3724          handy in that case.</para>
3725        </refsect1>
3726
3727        <refsect1>
3728          <title>Examples</title>
3729
3730          <para>One typically wants interface information to be
3731          available at compile-time (or, in many cases, at read-time).
3732          A typical idiom would be:</para>
3733
3734          <programlisting format="linespecific">(eval-when (:compile-toplevel :execute)
3735  (use-interface-dir :GTK))</programlisting>
3736
3737          <para>Using the :GTK interface directory makes available
3738          information on
3739          foreign types, functions, and constants.  It's generally
3740          necessary to
3741          load foreign libraries before actually calling the
3742          foreign code, which for GTK can be done like this:</para>
3743
3744          <programlisting>(load-gtk-libraries)</programlisting>
3745
3746          <para>It should now be possible to do things like:</para>
3747
3748          <programlisting>(#_gtk_widget_destroy w)</programlisting>
3749        </refsect1>
3750      </refentry>
3751
3752      <refentry id="f_unuse-interface-dir">
3753        <indexterm zone="f_unuse-interface-dir">
3754          <primary>unuse-interface-dir</primary>
3755        </indexterm>
3756
3757        <refnamediv>
3758          <refname>UNUSE-INTERFACE-DIR</refname>
3759          <refpurpose></refpurpose>
3760          <refclass>Function</refclass>
3761        </refnamediv>
3762
3763        <refsynopsisdiv>
3764          <synopsis>
3765            <function>unuse-interface-dir</function> dir-id
3766          </synopsis>
3767        </refsynopsisdiv>
3768
3769        <refsect1>
3770          <title>Values</title>
3771
3772          <variablelist>
3773            <varlistentry>
3774              <term>dir-id</term>
3775
3776              <listitem>
3777                <para>A keyword whose pname, mapped to lower case, names a
3778                subdirectory of &#34;ccl:headers;&#34; (or
3779                "ccl:darwin-headers;")</para>
3780              </listitem>
3781            </varlistentry>
3782          </variablelist>
3783        </refsect1>
3784
3785        <refsect1>
3786          <title>Description</title>
3787
3788          <para>Tells &CCL; to remove the interface directory denoted by
3789          dir-id from the list of interface directories which are
3790          consulted for
3791          foreign type and function information. Returns T if the directory
3792          was on the search list, NIL otherwise.</para>
3793        </refsect1>
3794      </refentry>
3795
3796      <refentry id="f_terminate-when-unreachable">
3797        <indexterm zone="f_terminate-when-unreachable">
3798          <primary>terminate-when-unreachable</primary>
3799        </indexterm>
3800
3801        <refnamediv>
3802          <refname>TERMINATE-WHEN-UNREACHABLE</refname>
3803          <refpurpose></refpurpose>
3804          <refclass>Function</refclass>
3805        </refnamediv>
3806
3807        <refsynopsisdiv>
3808          <synopsis>
3809            <function>terminate-when-unreachable</function> object
3810          </synopsis>
3811        </refsynopsisdiv>
3812
3813        <refsect1>
3814          <title>Values</title>
3815
3816          <variablelist>
3817            <varlistentry>
3818              <term>object</term>
3819
3820              <listitem>
3821                <para>A CLOS object of a class for which there exists
3822                a method of the generic function
3823                <function>ccl:terminate</function>.
3824                </para>
3825              </listitem>
3826            </varlistentry>
3827          </variablelist>
3828        </refsect1>
3829
3830        <refsect1>
3831          <title>Description</title>
3832
3833          <para>
3834            The "termination" mechanism is a way to have the garbage
3835            collector run a function right before an object is about to
3836            become garbage.  It is very similar to the "finalization"
3837            mechanism which Java has.  It is not standard Common Lisp,
3838            although other Lisp implementations have similar features.
3839            It is useful when there is some sort of special cleanup,
3840            deallocation, or releasing of resources which needs to happen
3841            when a certain object is no longer being used.
3842          </para>
3843
3844          <para>
3845            When the garbage collector discovers that an object is no
3846            longer referred to anywhere in the program, it deallocates
3847            that object, freeing its memory.  However, if
3848            <function>ccl:terminate-when-unreachable</function> has been
3849            called on the object at any time, the garbage collector first
3850            invokes the generic function <function>ccl:terminate</function>,
3851            passing it the object as a parameter.
3852          </para>
3853
3854          <para>
3855            Therefore, to make termination do something useful, you need to
3856            define a method on <function>ccl:terminate</function>.
3857          </para>
3858
3859          <para>
3860            Because calling
3861            <function>ccl:terminate-when-unreachable</function> only
3862            affects a single object, rather than all objects of its
3863            class, you
3864            may wish to put a call to it in the
3865            <function>initialize-instance</function> method of a
3866            class.  Of course, this is only appropriate if you do in fact
3867            want to use termination for all objects of a given class.
3868          </para>
3869        </refsect1>
3870
3871        <refsect1>
3872          <title>Example</title>
3873
3874      <programlisting format="linespecific">
3875(defclass resource-wrapper ()
3876  ((resource :accessor resource)))
3877
3878(defmethod initialize-instance :after ((x resource-wrapper) &amp;rest initargs)
3879  (ccl:terminate-when-unreachable x))
3880
3881(defmethod ccl:terminate ((x resource-wrapper))
3882  (when (resource x)
3883    (deallocate (resource x))))</programlisting>
3884        </refsect1>
3885
3886        <refsect1>
3887          <title>See Also</title>
3888
3889          <simplelist type="inline">
3890            <member><xref linkend="Tutorial--Allocating-Foreign-Data-on-the-Lisp-Heap"/></member>
3891          </simplelist>
3892        </refsect1>
3893
3894      </refentry>
3895
3896    </sect1>
3897  </chapter>
Note: See TracBrowser for help on using the repository browser.