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

Last change on this file since 8896 was 8896, checked in by mikel, 12 years ago

working on objective-c bridge docs

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