1 <chapter id="ffi"><title>The Foreign Function Interface</>
3 <para>This chapter describes &SBCL;'s interface to C programs and
4 libraries (and, since C interfaces are a sort of <foreignphrase>lingua
5 franca</> of the Unix world, to other programs and libraries in
8 <note><para>In the modern Lisp world, the usual term for this
9 functionality is Foreign Function Interface, or <acronym>FFI</>, where
10 despite the mention of <quote>function</> in this term, <acronym>FFI</> also
11 refers to direct manipulation of C data structures as well as
12 functions. The traditional &CMUCL; terminology is Alien Interface, and
13 while that older terminology is no longer used much in the system
14 documentation, it still reflected in internal names in the
15 implementation, notably in the name of the <literal>SB-ALIEN</>
16 package.</para></note>
18 <sect1><title>Introduction to the Foreign Function Interface</>
19 <!-- AKA "Introduction to Aliens" in the CMU CL manual -->
22 Because of Lisp's emphasis on dynamic memory allocation and garbage
23 collection, Lisp implementations use unconventional memory representations
24 for objects. This representation mismatch creates problems when a Lisp
25 program must share objects with programs written in another language. There
26 are three different approaches to establishing communication:
28 <listitem><para>The burden can be placed on the foreign program
29 (and programmer) by requiring the knowledge and use of the
30 representations used internally by the Lisp implementation.
31 This can require a considerable amount of <quote>glue</> code on the
32 C side, and that code tends to be sensitively dependent on the
33 internal implementation details of the Lisp system.</para></listitem>
34 <listitem><para>The Lisp system can automatically convert objects
35 back and forth between the Lisp and foreign representations.
36 This is convenient, but translation becomes prohibitively slow
37 when large or complex data structures must be shared. This approach
38 is supported by the &SBCL; <acronym>FFI</>, and used automatically
39 by the when passing integers and strings.</para></listitem>
40 <listitem><para>The Lisp program can directly manipulate foreign
41 objects through the use of extensions to the Lisp language.
45 <para>&SBCL;, like &CMUCL; before it,
46 relies primarily on the automatic conversion and direct manipulation
47 approaches. Aliens of simple scalar types are automatically converted,
48 complex types are directly manipulated in their foreign
49 representation. Furthermore, Lisp strings are represented internally
50 with null termination bytes so that they can be passed directly to
51 C interfaces without allocating new zero-terminated copies.</para>
53 <para>Any foreign objects that can't automatically be converted into
54 Lisp values are represented by objects of type <type>alien-value</>.
55 Since Lisp is a dynamically typed language, even foreign objects must
56 have a run-time type; this type information is provided by
57 encapsulating the raw pointer to the foreign data within an
58 <type>alien-value</> object.</para>
60 <para>The type language and operations on foreign types are
61 intentionally similar to those of the C language. And as discussed
62 above, they are applicable not only to communication with native C
63 programs, but also to programs in other languages which provide
64 C-level interfaces. </para>
68 <sect1><title>Foreign Types</>
69 <!-- AKA "Alien Types" in the CMU CL manual -->
71 <para>Alien types have a description language based on nested list
72 structure. For example the C type
78 has the corresponding &SBCL; FFI type
82 (b (array (* (struct foo)) 100)))</programlisting>
85 <sect2><title>Defining Foreign Types</>
88 Types may be either named or anonymous. With structure and union
89 types, the name is part of the type specifier, allowing recursively
90 defined types such as:
91 <programlisting>(struct foo (a (* (struct foo))))</programlisting>
92 An anonymous structure or union type is specified by using the name
93 <literal>nil</>. The <function>with-alien</> macro defines a local
94 scope which <quote>captures</> any named type definitions. Other types
95 are not inherently named, but can be given named abbreviations using
96 the <function>define-alien-type</> macro.
101 <sect2><title>Foreign Types and Lisp Types</>
104 The foreign types form a subsystem of the &SBCL; type system. An
105 <type>alien</> type specifier provides a way to use any foreign type as a
106 Lisp type specifier. For example
107 <programlisting>(typep foo '(alien (* int)))</programlisting>
108 can be used to determine whether <varname>foo</> is a pointer to a foreign
109 <type>int</>. <type>alien</> type specifiers can be used in the same ways
110 as ordinary Lisp type specifiers (like <type>string</>.) Alien type
111 declarations are subject to the same
112 precise type checking <!-- FIXME: should be linked to id="precisetypechecking" -->
113 as any other declaration.
117 Note that the type identifiers used in the
118 foreign type system overlap with native Lisp type
119 specifiers in some cases. For example, the type specifier
120 <type>(alien single-float)</type> is identical to <type>single-float</>, since
121 foreign floats are automatically converted to Lisp floats. When
122 <function>type-of</> is called on an alien value that is not automatically
123 converted to a Lisp value, then it will return an <type>alien</> type
129 <sect2><title>Foreign Type Specifiers</>
132 All foreign type names are exported from the <literal>sb-alien</>
133 package. Some foreign type names are also symbols in
134 the <literal>common-lisp</> package, in which case they are
135 reexported from the <literal>sb-alien</> package, so that
136 e.g. it is legal to refer to <type>sb-alien:single-float</>.
140 These are the basic foreign type specifiers:
141 <!-- FIXME: There must be some better way of formatting definitions
142 in DocBook than this. I haven't found it yet, but suggestions
143 or patches would be welcome. -->
147 The foreign type specifier <type>(* foo)</> describes a
148 pointer to an object of type <type>foo</>. A pointed-to type
149 <type>foo</> of <type>t</> indicates a pointer to anything,
150 similar to <type>void *</> in ANSI C. A null alien pointer can
151 be detected with the <function>sb-alien:null-alien</>
157 The foreign type specifier <type>(array foo &optional dimensions)</>
158 describes array of the specified <literal>dimensions</>, holding
159 elements of type <type>foo</>. Note that (unlike in C) <type>(* foo)</>
160 <type>(array foo)}</> are considered to be different types when
161 type checking is done. If equivalence of pointer and array types
162 is desired, it may be explicitly coerced using
163 <function>sb-alien:cast</>.
166 Arrays are accessed using <function>sb-alien:deref</>, passing
167 the indices as additional arguments. Elements are stored in
168 column-major order (as in C), so the first dimension determines
169 only the size of the memory block, and not the layout of the
170 higher dimensions. An array whose first dimension is variable
171 may be specified by using <literal>nil</> as the first dimension.
172 Fixed-size arrays can be allocated as array elements, structure
173 slots or <function>sb-alien:with-alien</> variables. Dynamic
174 arrays can only be allocated using <function>sb-alien:make-alien</>.
179 The foreign type specifier
180 <type>(sb-alien:struct name &rest fields)</>
181 describes a structure type with the specified <varname>name</> and
182 <varname>fields</>. Fields are allocated at the same offsets
183 used by the implementation's C compiler. If <varname>name</>
184 is <literal>nil</> then the structure is anonymous.
187 If a named foreign <type>struct</> specifier is passed to
188 <function>define-alien-type</> or <function>with-alien</>,
189 then this defines, respectively, a new global or local foreign
190 structure type. If no <varname>fields</> are specified, then
191 the fields are taken from the current (local or global) alien
192 structure type definition of <varname>name</>.
197 The foreign type specifier
198 <type>(sb-alien:union name &rest fields)</>
199 is similar to <type>sb-alien:struct</>, but describes a union type.
200 All fields are allocated at the same offset, and the size of the
201 union is the size of the largest field. The programmer must
202 determine which field is active from context.
207 The foreign type specifier <type>(sb-alien:enum name &rest specs)</>
208 describes an enumeration type that maps between integer values
209 and keywords. If <varname>name</> is <literal>nil</>, then the
210 type is anonymous. Each element of the <varname>specs</>
211 list is either a Lisp keyword, or a list <literal>(keyword value)</>.
212 <varname>value</> is an integer. If <varname>value</> is not
213 supplied, then it defaults to one greater than the value for
214 the preceding spec (or to zero if it is the first spec.)
219 The foreign type specifier <type>(sb-alien:signed &optional bits)</>
220 specifies a signed integer with the specified number of
221 <varname>bits</> precision. The upper limit on integer
222 precision is determined by the machine's word
223 size. If <varname>bits</> is not specified, the maximum
229 The foreign type specifier <type>(integer &optional bits)</> is
230 equivalent to the corresponding type specifier using
231 <type>sb-alien:signed</> instead of <type>integer</>.
236 The foreign type specifier
237 <type>(sb-alien:unsigned &optional bits)</>
238 is like corresponding type specifier using <type>sb-alien:signed</>
239 except that the variable is treated as an unsigned integer.
244 The foreign type specifier <type>(boolean &optional bits)</> is
245 similar to an enumeration type, but maps from Lisp <literal>nil</>
246 and <literal>t</> to C <literal>0</> and <literal>1</>
247 respectively. <varname>bits</> determines the amount of
248 storage allocated to hold the truth value.
253 The foreign type specifier <type>single-float</> describes a
254 floating-point number in IEEE single-precision format.
259 The foreign type specifier <type>double-float</> describes a
260 floating-point number in IEEE double-precision format.
265 The foreign type specifier
266 <type>(function result-type &rest arg-types)</>
267 describes a foreign function that takes arguments of the specified
268 <varname>arg-types</> and returns a result of type <type>result-type</>.
269 Note that the only context where a foreign <type>function</> type
270 is directly specified is in the argument to
271 <function>sb-alien:alien-funcall</>.
272 In all other contexts, foreign functions are represented by
273 foreign function pointer types: <type>(* (function ...))</>.
278 The foreign type specifier <type>sb-alien:system-area-pointer</>
279 describes a pointer which is represented in Lisp as a
280 <type>system-area-pointer</> object. &SBCL; exports this type from
281 <literal>sb-alien</> because &CMUCL; did, but tentatively (as of
282 the first draft of this section of the manual, 2002-07-04) it is
283 deprecated, since it doesn't seem to be required by user code.
288 The foreign type specifier <type>sb-alien:void</> is
289 used in function types to declare that no useful value
290 is returned. Using <function>alien-funcall</>
291 to call a <type>void</> foreign function will return
297 The foreign type specifier <type>sb-alien:c-string</>
298 is similar to <type>(* char)</>, but is interpreted as a
299 null-terminated string, and is automatically converted into a
300 Lisp string when accessed; or if the pointer is C <literal>NULL</>
301 or <literal>0</>, then accessing it gives Lisp <literal>nil</>.
304 Assigning a Lisp string to a <type>c-string</> structure field or
305 variable stores the contents of the string to the memory already
306 pointed to by that variable. When a foreign object of type
307 <type>(* char)</> is assigned to a <type>c-string</>, then the
308 <type>c-string</> pointer is assigned to. This allows
309 <type>c-string</> pointers to be initialized. For example:
310 <programlisting>(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
311 (define-alien-type nil (struct foo (str c-string)))
312 (defun make-foo (str) (let ((my-foo (make-alien (struct foo))))
313 (setf (slot my-foo 'str) (make-alien char (length str))
314 (slot my-foo 'str) str) my-foo))</programlisting>
315 Storing Lisp <literal>NIL</> in a <type>c-string</> writes C
316 <literal>NULL</> to the variable.
321 <literal>sb-alien</> also exports translations of these C type
322 specifiers as foreign type specifiers:
323 <type>sb-alien:char</>,
324 <type>sb-alien:short</>,
325 <type>sb-alien:int</>,
326 <type>sb-alien:long</>,
327 <type>sb-alien:unsigned-char</>,
328 <type>sb-alien:unsigned-short</>,
329 <type>sb-alien:unsigned-int</>,
330 <type>sb-alien:unsigned-long</>,
331 <type>sb-alien:float</>, and
332 <type>sb-alien:double</>.
340 <sect1><title>Operations On Foreign Values</>
341 <!-- AKA "Alien Operations" in the CMU CL manual -->
343 <para>This section describes how to read foreign values as Lisp
344 values, how to coerce foreign values to different kinds of foreign values, and
345 how to dynamically allocate and free foreign variables.</para>
347 <sect2><title>Accessing Foreign Values</>
349 <synopsis>(sb-alien:deref pointer-or-array &rest indices)</>
351 <para>The <function>sb-alien:deref</> function returns the value pointed to by
352 a foreign pointer, or the value of a foreign array element. When
353 dereferencing a pointer, an optional single index can be specified to
354 give the equivalent of C pointer arithmetic; this index is scaled by
355 the size of the type pointed to. When dereferencing an array, the
356 number of indices must be the same as the number of dimensions in the
357 array type. <function>deref</> can be set with <function>setf</> to
358 assign a new value.</para>
360 <synopsis>(sb-alien:slot struct-or-union &rest slot-names)</>
362 <para>The <function>sb-alien:slot</> function extracts the value of
363 the slot named <varname>slot-name</> from a foreign <type>struct</> or
364 <type>union</>. If <varname>struct-or-union</> is a pointer to a
365 structure or union, then it is automatically dereferenced.
366 <function>sb-alien:slot</> can be set with <function>setf</> to assign
367 a new value. Note that <varname>slot-name</> is evaluated, and need
368 not be a compile-time constant (but only constant slot accesses are
369 efficiently compiled.)</para>
373 <sect2><title>Coercing Foreign Values</>
375 <synopsis>(sb-alien:addr alien-expr)</>
378 The <function>sb-alien:addr</> macro
379 returns a pointer to the location specified by
380 <varname>alien-expr</>, which must be either a foreign variable, a use of
381 <function>sb-alien:deref</>, a use of <function>sb-alien:slot</>, or a use of
382 <function>sb-alien:extern-alien</>.
385 <synopsis>(sb-alien:cast foreign-value new-type)</>
387 <para>The <function>sb-alien:cast</>
388 converts <varname>foreign-value</> to a new foreign value with the specified
389 <varname>new-type</>. Both types, old and new, must be foreign pointer,
390 array or function types. Note that the resulting Lisp
391 foreign variable object
392 is not <function>eq</> to the
393 argument, but it does refer to the same foreign data bits.</para>
395 <synopsis>(sb-alien:sap-alien sap type)</>
397 <para>The <function>sb-alien:sap-alien</> function converts <varname>sap</>
398 (a system area pointer) to a foreign value with the specified
399 <varname>type</>. <varname>type</> is not evaluated.
400 As of 2002-07-04, it looks as though this and other SAP functionality
401 may become deprecated, since it shouldn't be needed by user code.
404 <para>The <varname>type</> must be some foreign pointer, array, or
407 <synopsis>(sb-alien:alien-sap foreign-value type)</>
409 <para>The <function>sb-alien:alien-sap</> function
410 returns the SAP which points to <varname>alien-value</>'s data.
411 As of 2002-07-04, it looks as though this and other SAP functionality
412 may become deprecated, since it shouldn't be needed by user code.
415 <para>The <varname>foreign-value</> must be of some foreign pointer,
416 array, or record type.</para>
420 <sect2><title>Foreign Dynamic Allocation</>
422 <para>Lisp code can call the C standard library functions
423 <function>malloc</> and <function>free</> to dynamically allocate and
424 deallocate foreign variables. The Lisp code shares the same allocator
425 with foreign C code, so it's OK for foreign code to call
426 <function>free</> on the result of Lisp
427 <function>sb-alien:make-alien</>, or for Lisp code to call
428 <function>sb-alien:free-alien</> on foreign objects allocated by C
431 <synopsis>(sb-alien:make-alien type size)</>
433 <para>The <function>sb-alien:make-alien</> macro
434 returns a dynamically allocated foreign value of the specified
435 <varname>type</> (which is not evaluated.) The allocated memory is not
436 initialized, and may contain arbitrary junk. If supplied,
437 <varname>size</> is an expression to evaluate to compute the size of the
438 allocated object. There are two major cases:
441 <para>When <varname>type</> is a foreign array type, an array of
442 that type is allocated and a pointer to it is returned. Note that you
443 must use <function>deref</> to change the result to an array before you
444 can use <function>deref</> to read or write elements:
446 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
447 (defvar *foo* (make-alien (array char 10)))
448 (type-of *foo*) => (alien (* (array (signed 8) 10)))
449 (setf (deref (deref foo) 0) 10) => 10</programlisting>
450 If supplied, <varname>size</> is used as the first dimension for the
454 <para>When <varname>type</> is any other foreign type, then an
455 object for that type is allocated, and a pointer to it is
456 returned. So <function>(make-alien int)</> returns a <type>(* int)</>.
457 If <varname>size</> is specified, then a block of that many
458 objects is allocated, with the result pointing to the first one.</para>
463 <synopsis>(sb-alien:free-alien foreign-value)</>
465 <para>The <function>sb-alien:free-alien</> function
466 frees the storage for <varname>foreign-value</>,
467 which must have been allocated with Lisp <function>make-alien</>
468 or C <function>malloc</>.</para>
470 <para>See also the <function>sb-alien:with-alien</> macro, which
471 allocates foreign values on the stack.</para>
475 <sect1><title>Foreign Variables</>
476 <!-- AKA "Alien Variables" in the CMU CL manual -->
479 Both local (stack allocated) and external (C global) foreign variables are
483 <sect2><title>Local Foreign Variables</>
485 <synopsis>(sb-alien:with-alien var-definitions &body body)</>
487 <para>The <function>with-alien</>
488 macro establishes local
491 alien types and names.
492 This form is analogous to defining a local variable in C: additional
493 storage is allocated, and the initial value is copied.
495 analogous to LET-allocated Lisp variables, since the variables
496 can't be captured in closures: they live only for the dynamic extent
497 of the body, and referring to them outside is a gruesome error.
500 <para>The <varname>var-definitions</> argument is a list of
501 variable definitions, each of the form
502 <programlisting>(name type &optional initial-value)</programlisting>
503 The names of the variables are established as symbol-macros; the bindings have
504 lexical scope, and may be assigned with <function>setq</>
505 or <function>setf</>.
508 <para>The <function>with-alien</> macro also establishes
509 a new scope for named structures
510 and unions. Any <varname>type</> specified for a variable may contain
511 named structure or union types with the slots specified. Within the
512 lexical scope of the binding specifiers and body, a locally defined
513 foreign structure type <type>foo</> can be referenced by its name using
514 <type>(struct foo)</>.
519 <sect2><title>External Foreign Variables</>
522 External foreign names are strings, and Lisp names are symbols. When
523 an external foreign value is represented using a Lisp variable, there
524 must be a way to convert from one name syntax into the other. The
525 macros <function>extern-alien</>, <function>define-alien-variable</> and
526 <function>define-alien-routine</> use this conversion heuristic:
528 <listitem><para>Alien names are converted to Lisp names by uppercasing and
529 replacing underscores with hyphens.</para></listitem>
530 <listitem><para>Conversely, Lisp names are converted to alien names by
531 lowercasing and replacing hyphens with underscores.</para></listitem>
532 <listitem><para>Both the Lisp symbol and alien string names may be
533 separately specified by using a list of the form
534 <programlisting>(alien-string lisp-symbol)</></para></listitem>
537 <synopsis>(sb-alien:define-alien-variable name type)</>
540 The <function>define-alien-variable</> macro
541 defines <varname>name</> as an external foreign variable of the
542 specified foreign <type>type</>. <varname>name</> and <type>type</> are not
543 evaluated. The Lisp name of the variable (see above) becomes a
544 global alien variable. Global alien variables
545 are effectively ``global symbol macros''; a reference to the
546 variable fetches the contents of the external variable. Similarly,
547 setting the variable stores new contents---the new contents must be
548 of the declared <type>type</>. Someday, they may well be implemented
549 using the &ANSI; <function>define-symbol-macro</> mechanism, but
550 as of &SBCL; 0.7.5, they are still implemented using an older
551 more-or-less parallel mechanism inherited from &CMUCL;.
555 For example, to access a C-level counter <varname>foo</>, one could
558 (define-alien-variable "foo" int)
559 ;; Now it is possible to get the value of the C variable foo simply by
560 ;; referencing that Lisp variable:
563 (incf foo)</programlisting>
566 <synopsis>(sb-alien:get-errno)</>
569 Since in modern C libraries, the <varname>errno</> "variable" is typically
570 no longer a variable, but some some bizarre artificial construct
571 which behaves superficially like a variable within a given thread,
572 it can no longer reliably be accessed through the ordinary
573 <varname>define-alien-variable</> mechanism. Instead, &SBCL; provides
574 the operator <function>sb-alien:get-errno</> to allow Lisp code to read it.
577 <synopsis>(sb-alien:extern-alien name type)</>
580 The <function>extern-alien</> macro
581 returns an alien with the specified <type>type</> which
582 points to an externally defined value. <varname>name</> is not evaluated,
583 and may be either a string or a symbol. <type>type</> is
584 an unevaluated alien type specifier.
589 <sect1><title>Foreign Data Structure Examples</>
590 <!-- AKA "Alien Data Structure Example" in the CMU CL manual -->
593 Now that we have alien types, operations and variables, we can manipulate
594 foreign data structures. This C declaration
600 can be translated into the following alien type:
601 <programlisting>(define-alien-type nil
604 (b (array (* (struct foo)) 100))))</programlisting>
608 Once the <type>foo</> alien type has been defined as above,
612 f.b[7].a</programlisting>
613 can be translated in this way:
615 (with-alien ((f (struct foo)))
616 (slot (deref (slot f 'b) 7) 'a)
618 ;; Do something with f...
623 Or consider this example of an external C variable and some accesses:
631 extern struct c_struct *my_struct;
634 my_struct = my_struct->n;</programlisting>
635 which can be manipulated in Lisp like this:
637 (define-alien-type nil
645 (define-alien-variable "my_struct" (* c-struct))
646 (incf (slot my-struct 'x))
647 (setf (slot my-struct 'a) 5)
648 (setq my-struct (slot my-struct 'n))</programlisting>
653 <sect1><title>Loading Unix Object Files</>
656 Foreign object files can be loaded into the running Lisp process by
657 calling the functions <function>load-foreign</> or
658 <function>load-1-foreign</>.
661 <para> The <function>sb-alien:load-1-foreign</> function is the more
662 primitive of the two operations. It loads a single object file. into
663 the currently running Lisp. The external symbols defining routines and
664 variables are made available for future external references (e.g. by
665 <function>extern-alien</>). Forward references to foreign symbols
666 aren't supported: <function>load-1-foreign</> must be run before any
667 of the defined symbols are referenced.
670 <para><function>sb-alien:load-foreign</> is built in terms of
671 <function>load-1-foreign</> and some other machinery
672 like <function>sb-ext:run-program</>.
673 It accepts a list of files and libraries,
674 and runs the linker on the files and
675 libraries, creating an absolute Unix object file which is then
676 processed by <function>load-1-foreign</>.</para>
678 <para> Note that as of &SBCL; 0.7.5, all foreign code (code loaded
679 with <function>load-1-function</> or <function>load-function</>) is
680 lost when a Lisp core is saved with
681 <function>sb-ext:save-lisp-and-die</>, and no attempt is made to
682 restore it when the core is loaded. Historically this has been an
683 annoyance both for &SBCL; users and for &CMUCL; users.
684 It's hard to solve this problem completely cleanly, but some
685 generally-reliable partial solution might be useful. Once someone in
686 either camp gets sufficiently annoyed to create it, some mechanism for
687 automatically restoring foreign code is likely to be added.</para>
691 <sect1><title>Foreign Function Calls</>
694 The foreign function call interface allows a Lisp program to call
695 functions written in other languages using the C calling convention.
699 Lisp sets up various interrupt handling routines and other environment
700 information when it first starts up, and expects these to be in place
701 at all times. The C functions called by Lisp should either not change
702 the environment, especially the interrupt entry points, or should make
703 sure that these entry points are restored when the C function returns
704 to Lisp. If a C function makes changes without restoring things to the
705 way they were when the C function was entered, there is no telling
709 <sect2><title>The <function>alien-funcall</> Primitive</title>
711 <synopsis>(sb-alien:alien-funcall alien-function &rest arguments)</>
714 The <function>alien-funcall</> function is the foreign function call
715 primitive: <varname>alien-function</> is called with the supplied
716 <varname>arguments</> and its C return value is returned as a Lisp value.
717 The <varname>alien-function</> is an arbitrary
718 run-time expression; to refer to a constant function, use
719 <function>extern-alien</> or a value defined by
720 <function>define-alien-routine</>.
724 The type of <function>alien-function</>
725 must be <type>(alien (function ...))</>
726 or <type>(alien (* (function ...)))</>.
727 The function type is used to
728 determine how to call the function (as though it was declared with
729 a prototype.) The type need not be known at compile time, but only
730 known-type calls are efficiently compiled. Limitations:
732 <listitem><para>Structure type return values are not implemented.</></>
733 <listitem><para>Passing of structures by value is not implemented.</></>
737 Here is an example which allocates a <type>(struct foo)</>, calls a foreign
738 function to initialize it, then returns a Lisp vector of all the
739 <type>(* (struct foo))</> objects filled in by the foreign call:
741 ;; Allocate a foo on the stack.
742 (with-alien ((f (struct foo)))
743 ;; Call some C function to fill in foo fields.
744 (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
746 ;; Find how many foos to use by getting the A field.
747 (let* ((num (slot f 'a))
748 (result (make-array num)))
749 ;; Get a pointer to the array so that we don't have to keep extracting it:
750 (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
751 ;; Loop over the first N elements and stash them in the result vector.
753 (setf (svref result i) (deref (deref a) i)))
755 result)))</programlisting>
760 <sect2><title>The <function>define-alien-routine</> Macro</>
762 <synopsis>(sb-alien:define-alien-routine} name result-type &rest arg-specifiers)</>
765 The <function>define-alien-routine</> macro is a convenience
766 for automatically generating Lisp
767 interfaces to simple foreign functions. The primary feature is the
768 parameter style specification, which translates the C
769 pass-by-reference idiom into additional return values.
773 <varname>name</> is usually a string external symbol, but may also be a
774 symbol Lisp name or a list of the foreign name and the Lisp name.
775 If only one name is specified, the other is automatically derived
776 as for <function>extern-alien</>.
777 <varname>result-type</> is the alien type of the return value.
781 Each element of the <varname>arg-specifiers</> list
782 specifies an argument to the foreign function, and is
784 <programlisting>(aname atype &optional style)</programlisting>
785 <varname>aname</> is the symbol name of the argument to the constructed
786 function (for documentation). <varname>atype</> is the alien type of
787 corresponding foreign argument. The semantics of the actual call
788 are the same as for <function>alien-funcall</>. <varname>style</>
789 specifies how this argument should be handled at call and return time,
790 and should be one of the following
792 <listitem><para><varname>:in</>specifies that the argument is
793 passed by value. This is the default. <varname>:in</> arguments
794 have no corresponding return value from the Lisp function.
796 <listitem><para><varname>:copy</> is similar to <varname>:in</>,
797 but the argument is copied
798 to a pre-allocated object and a pointer to this object is passed
799 to the foreign routine.</para></listitem>
800 <listitem><para><varname>:out</> specifies a pass-by-reference
801 output value. The type of the argument must be a pointer to
802 a fixed-sized object (such as an integer or pointer).
803 <varname>:out</> and <varname>:in-out</> style cannot
804 be used with pointers to arrays, records or functions. An
805 object of the correct size is allocated on the stack, and
806 its address is passed to the foreign function. When the
807 function returns, the contents
808 of this location are returned as one of the values of the Lisp
809 function (and the location is automatically deallocated).
811 <listitem><para><varname>:in-out</> is a combination of
812 <varname>:copy</> and <varname>:out</>.
813 The argument is copied to a pre-allocated object and a pointer to
814 this object is passed to the foreign routine. On return, the
815 contents of this location is returned as an additional value.
822 Any efficiency-critical foreign interface function should be inline
823 expanded, which can be done by preceding the
824 <function>define-alien-routine</> call with:
825 <programlisting>(declaim (inline lisp-name))</programlisting>
826 In addition to avoiding the Lisp call overhead, this allows
827 pointers, word-integers and floats to be passed using non-descriptor
828 representations, avoiding consing.)
834 <sect2><title><function>define-alien-routine</> Example</title>
837 Consider the C function <function>cfoo</>
838 with the following calling convention:
843 char *a; /* update */
846 /* body of cfoo(...) */
848 This can be described by the following call to
849 <function>define-alien-routine</>:
851 (define-alien-routine "cfoo" void
854 (i int :out))</programlisting>
855 The Lisp function <function>cfoo</> will have
856 two arguments (<varname>str</> and <varname>a</>)
857 and two return values (<varname>a</> and <varname>i</>).
861 <sect2><title>Calling Lisp From C</>
864 Calling Lisp functions from C is sometimes possible, but is extremely
865 hackish and poorly supported as of &SBCL; 0.7.5.
866 See <function>funcall0</> ... <function>funcall3</> in
867 the runtime system. The
868 arguments must be valid &SBCL; object descriptors (so that
870 left-shifted by 2.) As of &SBCL; 0.7.5, the format
871 of object descriptors is documented only by the source code and
872 by the old &CMUCL; "INTERNALS" documentation.</para>
874 <para> Note that the garbage collector moves objects, and won't be
875 able to fix up any references in C variables, so either turn GC off or
876 don't keep Lisp pointers in C data unless they are to statically
877 allocated objects. It is possible to use the
878 <function>sb-ext:purify</> function to place live data structures in
879 static space so that they won't move during GC. </para>
881 <!-- FIXME: This is a "changebar" section from the CMU CL manual.
882 I (WHN 2002-07-14) am not very familiar with this content, so
883 I'm not immediately prepared to try to update it for SBCL, and
884 I'm not feeling masochistic enough to work to encourage this
885 kind of low-level hack anyway. However, I acknowledge that callbacks
886 are sometimes really really necessary, so I include the original
887 text in case someone is hard-core enough to benefit from it. If
888 anyone brings the information up to date for SBCL, it belong
889 either in the main manual or on a CLiki SBCL Internals page.
890 LaTeX \subsection{Accessing Lisp Arrays}
892 LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
893 LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
894 LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
895 LaTeX use and this memory is typically about 8 MB above the start of the C
896 LaTeX heap. Thus, only about 8 MB of memory can be dynamically
899 LaTeX To overcome this limitation, it is possible to access the content of
900 LaTeX Lisp arrays which are limited only by the amount of physical memory
901 LaTeX and swap space available. However, this technique is only useful if
902 LaTeX the foreign function takes pointers to memory instead of allocating
903 LaTeX memory for itself. In latter case, you will have to modify the
904 LaTeX foreign functions.
906 LaTeX This technique takes advantage of the fact that \cmucl{} has
907 LaTeX specialized array types (\pxlref{specialized-array-types}) that match
908 LaTeX a typical C array. For example, a \code{(simple-array double-float
909 LaTeX (100))} is stored in memory in essentially the same way as the C
910 LaTeX array \code{double x[100]} would be. The following function allows us
911 LaTeX to get the physical address of such a Lisp array:
912 LaTeX \begin{example}
913 LaTeX (defun array-data-address (array)
914 LaTeX "Return the physical address of where the actual data of an array is
917 LaTeX ARRAY must be a specialized array type in CMU Lisp. This means ARRAY
918 LaTeX must be an array of one of the following types:
922 LaTeX (unsigned-byte 32)
923 LaTeX (unsigned-byte 16)
924 LaTeX (unsigned-byte 8)
925 LaTeX (signed-byte 32)
926 LaTeX (signed-byte 16)
927 LaTeX (signed-byte 8)
929 LaTeX (declare (type (or #+signed-array (array (signed-byte 8))
930 LaTeX #+signed-array (array (signed-byte 16))
931 LaTeX #+signed-array (array (signed-byte 32))
932 LaTeX (array (unsigned-byte 8))
933 LaTeX (array (unsigned-byte 16))
934 LaTeX (array (unsigned-byte 32))
935 LaTeX (array single-float)
936 LaTeX (array double-float))
938 LaTeX (optimize (speed 3) (safety 0))
939 LaTeX (ext:optimize-interface (safety 3)))
940 LaTeX ;; with-array-data will get us to the actual data. However, because
941 LaTeX ;; the array could have been displaced, we need to know where the
942 LaTeX ;; data starts.
943 LaTeX (lisp::with-array-data ((data array)
946 LaTeX (declare (ignore end))
947 LaTeX ;; DATA is a specialized simple-array. Memory is laid out like this:
949 LaTeX ;; byte offset Value
950 LaTeX ;; 0 type code (should be 70 for double-float vector)
951 LaTeX ;; 4 4 * number of elements in vector
952 LaTeX ;; 8 1st element of vector
955 LaTeX (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
956 LaTeX (type-size (let ((type (array-element-type data)))
957 LaTeX (cond ((or (equal type '(signed-byte 8))
958 LaTeX (equal type '(unsigned-byte 8)))
960 LaTeX ((or (equal type '(signed-byte 16))
961 LaTeX (equal type '(unsigned-byte 16)))
963 LaTeX ((or (equal type '(signed-byte 32))
964 LaTeX (equal type '(unsigned-byte 32)))
966 LaTeX ((equal type 'single-float)
968 LaTeX ((equal type 'double-float)
971 LaTeX (error "Unknown specialized array element type"))))))
972 LaTeX (declare (type (unsigned-byte 32) addr)
973 LaTeX (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
974 LaTeX (system:int-sap (the (unsigned-byte 32)
975 LaTeX (+ addr (* type-size start)))))))
978 LaTeX Assume we have the C function below that we wish to use:
979 LaTeX \begin{example}
980 LaTeX double dotprod(double* x, double* y, int n)
983 LaTeX double sum = 0;
985 LaTeX for (k = 0; k < n; ++k) \{
986 LaTeX sum += x[k] * y[k];
990 LaTeX The following example generates two large arrays in Lisp, and calls the C
991 LaTeX function to do the desired computation. This would not have been
992 LaTeX possible using \code{malloc} or \code{make-alien} since we need about
993 LaTeX 16 MB of memory to hold the two arrays.
994 LaTeX \begin{example}
995 LaTeX (define-alien-routine "dotprod" double
996 LaTeX (x (* double-float) :in)
997 LaTeX (y (* double-float) :in)
1000 LaTeX (let ((x (make-array 1000000 :element-type 'double-float))
1001 LaTeX (y (make-array 1000000 :element-type 'double-float)))
1002 LaTeX ;; Initialize X and Y somehow
1003 LaTeX (let ((x-addr (system:int-sap (array-data-address x)))
1004 LaTeX (y-addr (system:int-sap (array-data-address y))))
1005 LaTeX (dotprod x-addr y-addr 1000000)))
1007 LaTeX In this example, it may be useful to wrap the inner \code{let}
1008 LaTeX expression in an \code{unwind-protect} that first turns off garbage
1009 LaTeX collection and then turns garbage collection on afterwards. This will
1010 LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
1011 LaTeX have obtained the (now erroneous) addresses but before the call to
1012 LaTeX \code{dotprod} is made.
1018 <sect1><title>Step-By-Step Example of the Foreign Function Interface</>
1021 This section presents a complete example of an interface to a somewhat
1022 complicated C function.
1026 Suppose you have the following C function which you want to be able to
1027 call from Lisp in the file <filename>test.c</>
1035 struct c_struct *c_function (i, s, r, a)
1042 struct c_struct *r2;
1044 printf("i = %d\n", i);
1045 printf("s = %s\n", s);
1046 printf("r->x = %d\n", r->x);
1047 printf("r->s = %s\n", r->s);
1048 for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
1049 r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
1051 r2->s = "a C string";
1057 It is possible to call this C function from Lisp using the file
1058 <filename>test.lisp</> containing
1060 (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
1061 (cl:in-package "TEST-C-CALL")
1063 ;;; Define the record C-STRUCT in Lisp.
1064 (define-alien-type nil
1069 ;;; Define the Lisp function interface to the C routine. It returns a
1070 ;;; pointer to a record of type C-STRUCT. It accepts four parameters:
1071 ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
1072 ;;; record; and A, a pointer to the array of 10 ints.
1074 ;;; The INLINE declaration eliminates some efficiency notes about heap
1075 ;;; allocation of alien values.
1076 (declaim (inline c-function))
1077 (define-alien-routine c-function
1078 (* (struct c-struct))
1081 (r (* (struct c-struct)))
1084 ;;; a function which sets up the parameters to the C function and
1085 ;;; actually calls it
1087 (with-alien ((ar (array int 10))
1088 (c-struct (struct c-struct)))
1089 (dotimes (i 10) ; Fill array.
1090 (setf (deref ar i) i))
1091 (setf (slot c-struct 'x) 20)
1092 (setf (slot c-struct 's) "a Lisp string")
1094 (with-alien ((res (* (struct c-struct))
1095 (c-function 5 "another Lisp string" (addr c-struct) ar)))
1096 (format t "~&back from C function~%")
1097 (multiple-value-prog1
1098 (values (slot res 'x)
1101 ;; Deallocate result. (after we are done referring to it:
1102 ;; "Pillage, *then* burn.")
1103 (free-alien res)))))</programlisting>
1107 To execute the above example, it is necessary to compile the C routine,
1109 <userinput>cc -c test.c</>
1110 (In order to enable incremental loading with some linkers, you may need
1112 <userinput>cc -G 0 -c test.c</>)
1116 Once the C code has been compiled, you can start up Lisp and load it in:
1118 Lisp should start up with its normal prompt.</para>
1122 compile the Lisp file. (This step can be done separately. You don't
1123 have to recompile every time.)
1124 <userinput>(compile-file "test.lisp")</>
1127 Within Lisp, load the foreign object file to define the necessary
1129 <userinput>(load-foreign "test.o")</>.
1130 This must be done before loading any code that refers
1135 Now you can load the compiled Lisp ("fasl") file into Lisp:
1136 <userinput>(load "test.fasl")</>
1137 And once the Lisp file is loaded, you can call the
1138 Lisp routine that sets up the parameters and calls the C
1140 <userinput>(test-c-call::call-cfun)</>
1144 The C routine should print the following information to standard output:
1145 <!-- FIXME: What should be here is a verbatim environment for computer
1146 output, but since I don't know one in DocBook, I made do with
1147 PROGRAMLISTING for now... -->
1148 <programlisting>i = 5
1149 s = another Lisp string
1151 r->s = a Lisp string
1161 a[9] = 9.</programlisting>
1162 After return from the C function,
1163 the Lisp wrapper function should print the following output:
1164 <programlisting>back from C function</programlisting>
1165 And upon return from the Lisp wrapper function,
1166 before the next prompt is printed, the
1167 Lisp read-eval-print loop should print the following return values:
1168 <!-- FIXME: As above, it's not a program listing, but computer output... -->