source: trunk/source/doc/src/09-ffi.xml @ 8567

Last change on this file since 8567 was 8567, checked in by rme, 13 years ago

Break up monolithic openmcl-documentation.xml file into chapters. Add file
top.xml, which includes all the chapters via xi:xinclude.

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