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 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 non-C-like memory representations
24 for objects. This representation mismatch creates friction when a Lisp
25 program must share objects with programs which expect C data. There
26 are three common 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, relies primarily on the
46 automatic conversion and direct manipulation approaches. The SB-ALIEN
47 package provices a facility wherein foreign values of simple scalar
48 types are automatically converted and complex types are directly
49 manipulated in their foreign representation. Additionally the
50 lower-level System Area Pointers (or SAPs) can be used where
51 necessary to provide untyped access to foreign memory.</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.</para>
65 <sect1><title>Foreign Types</>
66 <!-- AKA "Alien Types" in the CMU CL manual -->
68 <para>Alien types have a description language based on nested list
69 structure. For example the C type
70 <programlisting>struct foo {
74 has the corresponding &SBCL; FFI type
75 <programlisting>(struct foo
77 (b (array (* (struct foo)) 100)))</programlisting>
80 <sect2><title>Defining Foreign Types</>
83 Types may be either named or anonymous. With structure and union
84 types, the name is part of the type specifier, allowing recursively
85 defined types such as:
86 <programlisting>(struct foo (a (* (struct foo))))</programlisting>
87 An anonymous structure or union type is specified by using the name
88 <literal>nil</>. The <function>with-alien</> macro defines a local
89 scope which <quote>captures</> any named type definitions. Other types
90 are not inherently named, but can be given named abbreviations using
91 the <function>define-alien-type</> macro.
96 <sect2><title>Foreign Types and Lisp Types</>
99 The foreign types form a subsystem of the &SBCL; type system. An
100 <type>alien</> type specifier provides a way to use any foreign type as a
101 Lisp type specifier. For example,
102 <programlisting>(typep foo '(alien (* int)))</programlisting>
103 can be used to determine whether <varname>foo</> is a pointer to a foreign
104 <type>int</>. <type>alien</> type specifiers can be used in the same ways
105 as ordinary Lisp type specifiers (like <type>string</>.) Alien type
106 declarations are subject to the same
107 precise type checking <!-- FIXME: should be linked to id="precisetypechecking" -->
108 as any other declaration.
112 Note that the type identifiers used in the
113 foreign type system overlap with native Lisp type
114 specifiers in some cases. For example, the type specifier
115 <type>(alien single-float)</type> is identical to <type>single-float</>, since
116 foreign floats are automatically converted to Lisp floats. When
117 <function>type-of</> is called on an alien value that is not automatically
118 converted to a Lisp value, then it will return an <type>alien</> type
124 <sect2><title>Foreign Type Specifiers</>
127 All foreign type names are exported from the <literal>sb-alien</>
128 package. Some foreign type names are also symbols in
129 the <literal>common-lisp</> package, in which case they are
130 reexported from the <literal>sb-alien</> package, so that
131 e.g. it is legal to refer to <type>sb-alien:single-float</>.
135 These are the basic foreign type specifiers:
136 <!-- FIXME: There must be some better way of formatting definitions
137 in DocBook than this. I haven't found it yet, but suggestions
138 or patches would be welcome. -->
142 The foreign type specifier <type>(* foo)</> describes a
143 pointer to an object of type <type>foo</>. A pointed-to type
144 <type>foo</> of <type>t</> indicates a pointer to anything,
145 similar to <type>void *</> in ANSI C. A null alien pointer can
146 be detected with the <function>sb-alien:null-alien</>
152 The foreign type specifier <type>(array foo &optional dimensions)</>
153 describes array of the specified <literal>dimensions</>, holding
154 elements of type <type>foo</>. Note that (unlike in C) <type>(* foo)</>
155 <type>(array foo)}</> are considered to be different types when
156 type checking is done. If equivalence of pointer and array types
157 is desired, it may be explicitly coerced using
158 <function>sb-alien:cast</>.
161 Arrays are accessed using <function>sb-alien:deref</>, passing
162 the indices as additional arguments. Elements are stored in
163 column-major order (as in C), so the first dimension determines
164 only the size of the memory block, and not the layout of the
165 higher dimensions. An array whose first dimension is variable
166 may be specified by using <literal>nil</> as the first dimension.
167 Fixed-size arrays can be allocated as array elements, structure
168 slots or <function>sb-alien:with-alien</> variables. Dynamic
169 arrays can only be allocated using <function>sb-alien:make-alien</>.
174 The foreign type specifier
175 <type>(sb-alien:struct name &rest fields)</>
176 describes a structure type with the specified <varname>name</> and
177 <varname>fields</>. Fields are allocated at the same offsets
178 used by the implementation's C compiler. If <varname>name</>
179 is <literal>nil</> then the structure is anonymous.
182 If a named foreign <type>struct</> specifier is passed to
183 <function>define-alien-type</> or <function>with-alien</>,
184 then this defines, respectively, a new global or local foreign
185 structure type. If no <varname>fields</> are specified, then
186 the fields are taken from the current (local or global) alien
187 structure type definition of <varname>name</>.
192 The foreign type specifier
193 <type>(sb-alien:union name &rest fields)</>
194 is similar to <type>sb-alien:struct</>, but describes a union type.
195 All fields are allocated at the same offset, and the size of the
196 union is the size of the largest field. The programmer must
197 determine which field is active from context.
202 The foreign type specifier <type>(sb-alien:enum name &rest specs)</>
203 describes an enumeration type that maps between integer values
204 and keywords. If <varname>name</> is <literal>nil</>, then the
205 type is anonymous. Each element of the <varname>specs</>
206 list is either a Lisp keyword, or a list <literal>(keyword value)</>.
207 <varname>value</> is an integer. If <varname>value</> is not
208 supplied, then it defaults to one greater than the value for
209 the preceding spec (or to zero if it is the first spec.)
214 The foreign type specifier <type>(sb-alien:signed &optional bits)</>
215 specifies a signed integer with the specified number of
216 <varname>bits</> precision. The upper limit on integer
217 precision is determined by the machine's word
218 size. If <varname>bits</> is not specified, the maximum
224 The foreign type specifier <type>(integer &optional bits)</> is
225 equivalent to the corresponding type specifier using
226 <type>sb-alien:signed</> instead of <type>integer</>.
231 The foreign type specifier
232 <type>(sb-alien:unsigned &optional bits)</>
233 is like corresponding type specifier using <type>sb-alien:signed</>
234 except that the variable is treated as an unsigned integer.
239 The foreign type specifier <type>(boolean &optional bits)</> is
240 similar to an enumeration type, but maps from Lisp <literal>nil</>
241 and <literal>t</> to C <literal>0</> and <literal>1</>
242 respectively. <varname>bits</> determines the amount of
243 storage allocated to hold the truth value.
248 The foreign type specifier <type>single-float</> describes a
249 floating-point number in IEEE single-precision format.
254 The foreign type specifier <type>double-float</> describes a
255 floating-point number in IEEE double-precision format.
260 The foreign type specifier
261 <type>(function result-type &rest arg-types)</>
262 describes a foreign function that takes arguments of the specified
263 <varname>arg-types</> and returns a result of type <type>result-type</>.
264 Note that the only context where a foreign <type>function</> type
265 is directly specified is in the argument to
266 <function>sb-alien:alien-funcall</>.
267 In all other contexts, foreign functions are represented by
268 foreign function pointer types: <type>(* (function ...))</>.
273 The foreign type specifier <type>sb-alien:system-area-pointer</>
274 describes a pointer which is represented in Lisp as a
275 <type>system-area-pointer</> object. &SBCL; exports this type from
276 <literal>sb-alien</> because &CMUCL; did, but tentatively (as of
277 the first draft of this section of the manual, &SBCL; 0.7.6) it is
278 deprecated, since it doesn't seem to be required by user code.
283 The foreign type specifier <type>sb-alien:void</> is
284 used in function types to declare that no useful value
285 is returned. Using <function>alien-funcall</>
286 to call a <type>void</> foreign function will return
292 The foreign type specifier <type>sb-alien:c-string</>
293 is similar to <type>(* char)</>, but is interpreted as a
294 null-terminated string, and is automatically converted into a
295 Lisp string when accessed; or if the pointer is C <literal>NULL</>
296 or <literal>0</>, then accessing it gives Lisp <literal>nil</>.
297 Lisp strings are stored with a trailing NUL termination, so no
298 copying (either by the user or the implementation) is necessary
299 when passing them to foreign code.
302 Assigning a Lisp string to a <type>c-string</> structure field or
303 variable stores the contents of the string to the memory already
304 pointed to by that variable. When a foreign object of type
305 <type>(* char)</> is assigned to a <type>c-string</>, then the
306 <type>c-string</> pointer is assigned to. This allows
307 <type>c-string</> pointers to be initialized. For example:
308 <programlisting>(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
309 (define-alien-type nil (struct foo (str c-string)))
310 (defun make-foo (str) (let ((my-foo (make-alien (struct foo))))
311 (setf (slot my-foo 'str) (make-alien char (length str))
312 (slot my-foo 'str) str) my-foo))</programlisting>
313 Storing Lisp <literal>NIL</> in a <type>c-string</> writes C
314 <literal>NULL</> to the variable.
319 <literal>sb-alien</> also exports translations of these C type
320 specifiers as foreign type specifiers:
321 <type>sb-alien:char</>,
322 <type>sb-alien:short</>,
323 <type>sb-alien:int</>,
324 <type>sb-alien:long</>,
325 <type>sb-alien:unsigned-char</>,
326 <type>sb-alien:unsigned-short</>,
327 <type>sb-alien:unsigned-int</>,
328 <type>sb-alien:unsigned-long</>,
329 <type>sb-alien:float</>, and
330 <type>sb-alien:double</>.
338 <sect1><title>Operations On Foreign Values</>
339 <!-- AKA "Alien Operations" in the CMU CL manual -->
341 <para>This section describes how to read foreign values as Lisp
342 values, how to coerce foreign values to different kinds of foreign values, and
343 how to dynamically allocate and free foreign variables.</para>
345 <sect2><title>Accessing Foreign Values</>
347 <synopsis>(sb-alien:deref pointer-or-array &rest indices)</>
349 <para>The <function>sb-alien:deref</> function returns the value pointed to by
350 a foreign pointer, or the value of a foreign array element. When
351 dereferencing a pointer, an optional single index can be specified to
352 give the equivalent of C pointer arithmetic; this index is scaled by
353 the size of the type pointed to. When dereferencing an array, the
354 number of indices must be the same as the number of dimensions in the
355 array type. <function>deref</> can be set with <function>setf</> to
356 assign a new value.</para>
358 <synopsis>(sb-alien:slot struct-or-union &rest slot-names)</>
360 <para>The <function>sb-alien:slot</> function extracts the value of
361 the slot named <varname>slot-name</> from a foreign <type>struct</> or
362 <type>union</>. If <varname>struct-or-union</> is a pointer to a
363 structure or union, then it is automatically dereferenced.
364 <function>sb-alien:slot</> can be set with <function>setf</> to assign
365 a new value. Note that <varname>slot-name</> is evaluated, and need
366 not be a compile-time constant (but only constant slot accesses are
367 efficiently compiled.)</para>
369 <sect3><title>Untyped memory</>
371 <para>As noted at the beginning of the chapter, the System Area
372 Pointer facilities allow untyped access to foreign memory. SAPs can
373 be converted to and from the usual typed foreign values using
374 <function>sap-alien</function> and <function>alien-sap</function>
375 (described elsewhere), and also to and from integers - raw machine
376 addresses. They should thus be used with caution; corrupting the Lisp
377 heap or other memory with SAPs is trivial.</para>
379 <synopsis>(sb-sys:int-sap machine-address)</>
381 <para>Creates a SAP pointing at the virtual address
382 <varname>machine-address</varname>. </para>
384 <synopsis>(sb-sys:sap-ref-32 sap offset)</>
386 <para>Access the value of the memory location at
387 <varname>offset</varname> bytes from <varname>sap</varname>. This form
388 may also be used with <function>setf</function> to alter the memory at
389 that location.</para>
391 <synopsis>(sb-sys:sap= sap1 sap2)</>
393 <para>Compare <varname>sap1</varname> and <varname>sap2</varname> for
396 <para>Similarly named functions exist for accessing other sizes of
397 word, other comparisons, and other conversions. The reader is invited
398 to use <function>apropos</function> and <function>describe</function>
399 for more details</para>
401 (apropos "sap" :sb-sys)
405 <sect2><title>Coercing Foreign Values</>
407 <synopsis>(sb-alien:addr alien-expr)</>
410 The <function>sb-alien:addr</> macro
411 returns a pointer to the location specified by
412 <varname>alien-expr</>, which must be either a foreign variable, a use of
413 <function>sb-alien:deref</>, a use of <function>sb-alien:slot</>, or a use of
414 <function>sb-alien:extern-alien</>.
417 <synopsis>(sb-alien:cast foreign-value new-type)</>
419 <para>The <function>sb-alien:cast</>
420 converts <varname>foreign-value</> to a new foreign value with the specified
421 <varname>new-type</>. Both types, old and new, must be foreign pointer,
422 array or function types. Note that the resulting Lisp
423 foreign variable object
424 is not <function>eq</> to the
425 argument, but it does refer to the same foreign data bits.</para>
427 <synopsis>(sb-alien:sap-alien sap type)</>
429 <para>The <function>sb-alien:sap-alien</> function converts <varname>sap</>
430 (a system area pointer) to a foreign value with the specified
431 <varname>type</>. <varname>type</> is not evaluated.
434 <para>The <varname>type</> must be some foreign pointer, array, or
437 <synopsis>(sb-alien:alien-sap foreign-value type)</>
439 <para>The <function>sb-alien:alien-sap</> function
440 returns the SAP which points to <varname>alien-value</>'s data.
443 <para>The <varname>foreign-value</> must be of some foreign pointer,
444 array, or record type.</para>
448 <sect2><title>Foreign Dynamic Allocation</>
450 <para>Lisp code can call the C standard library functions
451 <function>malloc</> and <function>free</> to dynamically allocate and
452 deallocate foreign variables. The Lisp code shares the same allocator
453 with foreign C code, so it's OK for foreign code to call
454 <function>free</> on the result of Lisp
455 <function>sb-alien:make-alien</>, or for Lisp code to call
456 <function>sb-alien:free-alien</> on foreign objects allocated by C
459 <synopsis>(sb-alien:make-alien type size)</>
461 <para>The <function>sb-alien:make-alien</> macro
462 returns a dynamically allocated foreign value of the specified
463 <varname>type</> (which is not evaluated.) The allocated memory is not
464 initialized, and may contain arbitrary junk. If supplied,
465 <varname>size</> is an expression to evaluate to compute the size of the
466 allocated object. There are two major cases:
469 <para>When <varname>type</> is a foreign array type, an array of
470 that type is allocated and a pointer to it is returned. Note that you
471 must use <function>deref</> to change the result to an array before you
472 can use <function>deref</> to read or write elements:
474 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
475 (defvar *foo* (make-alien (array char 10)))
476 (type-of *foo*) => (alien (* (array (signed 8) 10)))
477 (setf (deref (deref foo) 0) 10) => 10</programlisting>
478 If supplied, <varname>size</> is used as the first dimension for the
482 <para>When <varname>type</> is any other foreign type, then an
483 object for that type is allocated, and a pointer to it is
484 returned. So <function>(make-alien int)</> returns a <type>(* int)</>.
485 If <varname>size</> is specified, then a block of that many
486 objects is allocated, with the result pointing to the first one.</para>
491 <synopsis>(sb-alien:free-alien foreign-value)</>
493 <para>The <function>sb-alien:free-alien</> function
494 frees the storage for <varname>foreign-value</>,
495 which must have been allocated with Lisp <function>make-alien</>
496 or C <function>malloc</>.</para>
498 <para>See also the <function>sb-alien:with-alien</> macro, which
499 allocates foreign values on the stack.</para>
503 <sect1><title>Foreign Variables</>
504 <!-- AKA "Alien Variables" in the CMU CL manual -->
507 Both local (stack allocated) and external (C global) foreign variables are
511 <sect2><title>Local Foreign Variables</>
513 <synopsis>(sb-alien:with-alien var-definitions &body body)</>
515 <para>The <function>with-alien</>
516 macro establishes local
519 alien types and names.
520 This form is analogous to defining a local variable in C: additional
521 storage is allocated, and the initial value is copied.
523 analogous to LET-allocated Lisp variables, since the variables
524 can't be captured in closures: they live only for the dynamic extent
525 of the body, and referring to them outside is a gruesome error.
528 <para>The <varname>var-definitions</> argument is a list of
529 variable definitions, each of the form
530 <programlisting>(name type &optional initial-value)</programlisting>
531 The names of the variables are established as symbol-macros; the bindings have
532 lexical scope, and may be assigned with <function>setq</>
533 or <function>setf</>.
536 <para>The <function>with-alien</> macro also establishes
537 a new scope for named structures
538 and unions. Any <varname>type</> specified for a variable may contain
539 named structure or union types with the slots specified. Within the
540 lexical scope of the binding specifiers and body, a locally defined
541 foreign structure type <type>foo</> can be referenced by its name using
542 <type>(struct foo)</>.
547 <sect2><title>External Foreign Variables</>
550 External foreign names are strings, and Lisp names are symbols. When
551 an external foreign value is represented using a Lisp variable, there
552 must be a way to convert from one name syntax into the other. The
553 macros <function>extern-alien</>, <function>define-alien-variable</> and
554 <function>define-alien-routine</> use this conversion heuristic:
556 <listitem><para>Alien names are converted to Lisp names by uppercasing and
557 replacing underscores with hyphens.</para></listitem>
558 <listitem><para>Conversely, Lisp names are converted to alien names by
559 lowercasing and replacing hyphens with underscores.</para></listitem>
560 <listitem><para>Both the Lisp symbol and alien string names may be
561 separately specified by using a list of the form
562 <programlisting>(alien-string lisp-symbol)</></para></listitem>
565 <synopsis>(sb-alien:define-alien-variable name type)</>
568 The <function>define-alien-variable</> macro
569 defines <varname>name</> as an external foreign variable of the
570 specified foreign <type>type</>. <varname>name</> and <type>type</> are not
571 evaluated. The Lisp name of the variable (see above) becomes a
572 global alien variable. Global alien variables
573 are effectively ``global symbol macros''; a reference to the
574 variable fetches the contents of the external variable. Similarly,
575 setting the variable stores new contents---the new contents must be
576 of the declared <type>type</>. Someday, they may well be implemented
577 using the &ANSI; <function>define-symbol-macro</> mechanism, but
578 as of &SBCL; 0.7.5, they are still implemented using an older
579 more-or-less parallel mechanism inherited from &CMUCL;.
583 For example, to access a C-level counter <varname>foo</>, one could
586 (define-alien-variable "foo" int)
587 ;; Now it is possible to get the value of the C variable foo simply by
588 ;; referencing that Lisp variable:
591 (incf foo)</programlisting>
594 <synopsis>(sb-alien:get-errno)</>
597 Since in modern C libraries, the <varname>errno</> "variable" is typically
598 no longer a variable, but some bizarre artificial construct
599 which behaves superficially like a variable within a given thread,
600 it can no longer reliably be accessed through the ordinary
601 <varname>define-alien-variable</> mechanism. Instead, &SBCL; provides
602 the operator <function>sb-alien:get-errno</> to allow Lisp code to read it.
605 <synopsis>(sb-alien:extern-alien name type)</>
608 The <function>extern-alien</> macro
609 returns an alien with the specified <type>type</> which
610 points to an externally defined value. <varname>name</> is not evaluated,
611 and may be either a string or a symbol. <type>type</> is
612 an unevaluated alien type specifier.
617 <sect1><title>Foreign Data Structure Examples</>
618 <!-- AKA "Alien Data Structure Example" in the CMU CL manual -->
621 Now that we have alien types, operations and variables, we can manipulate
622 foreign data structures. This C declaration
628 can be translated into the following alien type:
629 <programlisting>(define-alien-type nil
632 (b (array (* (struct foo)) 100))))</programlisting>
636 Once the <type>foo</> alien type has been defined as above,
640 f.b[7].a</programlisting>
641 can be translated in this way:
643 (with-alien ((f (struct foo)))
644 (slot (deref (slot f 'b) 7) 'a)
646 ;; Do something with f...
651 Or consider this example of an external C variable and some accesses:
659 extern struct c_struct *my_struct;
662 my_struct = my_struct->n;</programlisting>
663 which can be manipulated in Lisp like this:
665 (define-alien-type nil
673 (define-alien-variable "my_struct" (* c-struct))
674 (incf (slot my-struct 'x))
675 (setf (slot my-struct 'a) 5)
676 (setq my-struct (slot my-struct 'n))</programlisting>
681 <sect1><title>Loading Unix Object Files</>
684 Foreign object files can be loaded into the running Lisp process by
685 calling the functions <function>load-foreign</> or
686 <function>load-1-foreign</>.
689 <para> The <function>sb-alien:load-1-foreign</> function is the more
690 primitive of the two operations. It loads a single object file. into
691 the currently running Lisp. The external symbols defining routines and
692 variables are made available for future external references (e.g. by
693 <function>extern-alien</>). Forward references to foreign symbols
694 aren't supported: <function>load-1-foreign</> must be run before any
695 of the defined symbols are referenced.
698 <para><function>sb-alien:load-foreign</> is built in terms of
699 <function>load-1-foreign</> and some other machinery
700 like <function>sb-ext:run-program</>.
701 It accepts a list of files and libraries,
702 and runs the linker on the files and
703 libraries, creating an absolute Unix object file which is then
704 processed by <function>load-1-foreign</>.</para>
706 <note><para>As of &SBCL; 0.7.5, all foreign code (code loaded
707 with <function>load-1-function</> or <function>load-function</>) is
708 lost when a Lisp core is saved with
709 <function>sb-ext:save-lisp-and-die</>, and no attempt is made to
710 restore it when the core is loaded. Historically this has been an
711 annoyance both for &SBCL; users and for &CMUCL; users.
712 It's hard to solve this problem completely cleanly, but some
713 generally-reliable partial solution might be useful. Once someone in
714 either camp gets sufficiently annoyed to create it, &SBCL; is
715 likely to adopt some mechanism for automatically restoring foreign
716 code when a saved core is loaded.</para></note>
720 <sect1><title>Foreign Function Calls</>
723 The foreign function call interface allows a Lisp program to call
724 many functions written in languages that use the C calling convention.
728 Lisp sets up various signal handling routines and other environment
729 information when it first starts up, and expects these to be in place
730 at all times. The C functions called by Lisp should not change the
731 environment, especially the signal handlers: the signal handlers
732 installed by Lisp typically have interesting flags set (e.g to request
733 machine context information, or for signal delivery on an alternate
734 stack) which the Lisp runtime relies on for correct operation.
735 Precise details of how this works may change without notice between
736 versions; the source, or the brain of a friendly &SBCL; developer,
737 is the only documentation. Users of a Lisp built with the :sb-thread
738 feature should also read the Threading section
739 <!-- FIXME I'm sure docbook has some syntax for internal links -->
740 of this manual</para>
742 <sect2><title>The <function>alien-funcall</> Primitive</title>
744 <synopsis>(sb-alien:alien-funcall alien-function &rest arguments)</>
747 The <function>alien-funcall</> function is the foreign function call
748 primitive: <varname>alien-function</> is called with the supplied
749 <varname>arguments</> and its C return value is returned as a Lisp value.
750 The <varname>alien-function</> is an arbitrary
751 run-time expression; to refer to a constant function, use
752 <function>extern-alien</> or a value defined by
753 <function>define-alien-routine</>.
757 The type of <function>alien-function</>
758 must be <type>(alien (function ...))</>
759 or <type>(alien (* (function ...)))</>.
760 The function type is used to
761 determine how to call the function (as though it was declared with
762 a prototype.) The type need not be known at compile time, but only
763 known-type calls are efficiently compiled. Limitations:
765 <listitem><para>Structure type return values are not implemented.</></>
766 <listitem><para>Passing of structures by value is not implemented.</></>
770 Here is an example which allocates a <type>(struct foo)</>, calls a foreign
771 function to initialize it, then returns a Lisp vector of all the
772 <type>(* (struct foo))</> objects filled in by the foreign call:
774 ;; Allocate a foo on the stack.
775 (with-alien ((f (struct foo)))
776 ;; Call some C function to fill in foo fields.
777 (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
779 ;; Find how many foos to use by getting the A field.
780 (let* ((num (slot f 'a))
781 (result (make-array num)))
782 ;; Get a pointer to the array so that we don't have to keep extracting it:
783 (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
784 ;; Loop over the first N elements and stash them in the result vector.
786 (setf (svref result i) (deref (deref a) i)))
788 result)))</programlisting>
793 <sect2><title>The <function>define-alien-routine</> Macro</>
795 <synopsis>(sb-alien:define-alien-routine} name result-type &rest arg-specifiers)</>
798 The <function>define-alien-routine</> macro is a convenience
799 for automatically generating Lisp
800 interfaces to simple foreign functions. The primary feature is the
801 parameter style specification, which translates the C
802 pass-by-reference idiom into additional return values.
806 <varname>name</> is usually a string external symbol, but may also be a
807 symbol Lisp name or a list of the foreign name and the Lisp name.
808 If only one name is specified, the other is automatically derived
809 as for <function>extern-alien</>.
810 <varname>result-type</> is the alien type of the return value.
814 Each element of the <varname>arg-specifiers</> list
815 specifies an argument to the foreign function, and is
817 <programlisting>(aname atype &optional style)</programlisting>
818 <varname>aname</> is the symbol name of the argument to the constructed
819 function (for documentation). <varname>atype</> is the alien type of
820 corresponding foreign argument. The semantics of the actual call
821 are the same as for <function>alien-funcall</>. <varname>style</>
822 specifies how this argument should be handled at call and return time,
823 and should be one of the following
825 <listitem><para><varname>:in</>specifies that the argument is
826 passed by value. This is the default. <varname>:in</> arguments
827 have no corresponding return value from the Lisp function.
829 <listitem><para><varname>:copy</> is similar to <varname>:in</>,
830 but the argument is copied
831 to a pre-allocated object and a pointer to this object is passed
832 to the foreign routine.</para></listitem>
833 <listitem><para><varname>:out</> specifies a pass-by-reference
834 output value. The type of the argument must be a pointer to
835 a fixed-sized object (such as an integer or pointer).
836 <varname>:out</> and <varname>:in-out</> style cannot
837 be used with pointers to arrays, records or functions. An
838 object of the correct size is allocated on the stack, and
839 its address is passed to the foreign function. When the
840 function returns, the contents
841 of this location are returned as one of the values of the Lisp
842 function (and the location is automatically deallocated).
844 <listitem><para><varname>:in-out</> is a combination of
845 <varname>:copy</> and <varname>:out</>.
846 The argument is copied to a pre-allocated object and a pointer to
847 this object is passed to the foreign routine. On return, the
848 contents of this location is returned as an additional value.
855 Any efficiency-critical foreign interface function should be inline
856 expanded, which can be done by preceding the
857 <function>define-alien-routine</> call with:
858 <programlisting>(declaim (inline lisp-name))</programlisting>
859 In addition to avoiding the Lisp call overhead, this allows
860 pointers, word-integers and floats to be passed using non-descriptor
861 representations, avoiding consing.)
867 <sect2><title><function>define-alien-routine</> Example</title>
870 Consider the C function <function>cfoo</>
871 with the following calling convention:
876 char *a; /* update */
879 /* body of cfoo(...) */
881 This can be described by the following call to
882 <function>define-alien-routine</>:
884 (define-alien-routine "cfoo" void
887 (i int :out))</programlisting>
888 The Lisp function <function>cfoo</> will have
889 two arguments (<varname>str</> and <varname>a</>)
890 and two return values (<varname>a</> and <varname>i</>).
894 <sect2><title>Calling Lisp From C</>
897 Calling Lisp functions from C is sometimes possible, but is extremely
898 hackish and poorly supported as of &SBCL; 0.7.5.
899 See <function>funcall0</> ... <function>funcall3</> in
900 the runtime system. The
901 arguments must be valid &SBCL; object descriptors (so that
903 left-shifted by 2.) As of &SBCL; 0.7.5, the format
904 of object descriptors is documented only by the source code and, in parts,
905 by the old &CMUCL; "INTERNALS" documentation.</para>
907 <para> Note that the garbage collector moves objects, and won't be
908 able to fix up any references in C variables. There are three
909 mechanisms for coping with this:
912 <listitem><para>The <function>sb-ext:purify</> moves all live Lisp
913 data into static or read-only areas such that it will never be moved
914 (or freed) again in the life of the Lisp session</para></listitem>
916 <listitem><para><function>sb-sys:with-pinned-objects</function> is a
917 macro which arranges for some set of objects to be pinned in memory
918 for the dynamic extent of its body forms. On ports which use the
919 generational garbage collector (as of &SBCL; 0.8.3, only the x86) this
920 has a page granularity - i.e. the entire 4k page or pages containing
921 the objects will be locked down. On other ports it is implemented by
922 turning off GC for the duration (so could be said to have a
923 whole-world granularity). </para></listitem>
925 <listitem><para>Disable GC, using the <function>without-gcing</function>
926 macro or <function>gc-off</function> call.</para></listitem>
929 <!-- FIXME: This is a "changebar" section from the CMU CL manual.
930 I (WHN 2002-07-14) am not very familiar with this content, so
931 I'm not immediately prepared to try to update it for SBCL, and
932 I'm not feeling masochistic enough to work to encourage this
933 kind of low-level hack anyway. However, I acknowledge that callbacks
934 are sometimes really really necessary, so I include the original
935 text in case someone is hard-core enough to benefit from it. If
936 anyone brings the information up to date for SBCL, it belong
937 either in the main manual or on a CLiki SBCL Internals page.
938 LaTeX \subsection{Accessing Lisp Arrays}
940 LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
941 LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
942 LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
943 LaTeX use and this memory is typically about 8 MB above the start of the C
944 LaTeX heap. Thus, only about 8 MB of memory can be dynamically
947 Empirically determined to be considerably >8Mb on this x86 linux
948 machine, but I don't know what the actual values are - dan 2003.09.01
950 Note that this technique is used in SB-GROVEL in the SBCL contrib
953 LaTeX To overcome this limitation, it is possible to access the content of
954 LaTeX Lisp arrays which are limited only by the amount of physical memory
955 LaTeX and swap space available. However, this technique is only useful if
956 LaTeX the foreign function takes pointers to memory instead of allocating
957 LaTeX memory for itself. In latter case, you will have to modify the
958 LaTeX foreign functions.
960 LaTeX This technique takes advantage of the fact that \cmucl{} has
961 LaTeX specialized array types (\pxlref{specialized-array-types}) that match
962 LaTeX a typical C array. For example, a \code{(simple-array double-float
963 LaTeX (100))} is stored in memory in essentially the same way as the C
964 LaTeX array \code{double x[100]} would be. The following function allows us
965 LaTeX to get the physical address of such a Lisp array:
966 LaTeX \begin{example}
967 LaTeX (defun array-data-address (array)
968 LaTeX "Return the physical address of where the actual data of an array is
971 LaTeX ARRAY must be a specialized array type in CMU Lisp. This means ARRAY
972 LaTeX must be an array of one of the following types:
976 LaTeX (unsigned-byte 32)
977 LaTeX (unsigned-byte 16)
978 LaTeX (unsigned-byte 8)
979 LaTeX (signed-byte 32)
980 LaTeX (signed-byte 16)
981 LaTeX (signed-byte 8)
983 LaTeX (declare (type (or #+signed-array (array (signed-byte 8))
984 LaTeX #+signed-array (array (signed-byte 16))
985 LaTeX #+signed-array (array (signed-byte 32))
986 LaTeX (array (unsigned-byte 8))
987 LaTeX (array (unsigned-byte 16))
988 LaTeX (array (unsigned-byte 32))
989 LaTeX (array single-float)
990 LaTeX (array double-float))
992 LaTeX (optimize (speed 3) (safety 0))
993 LaTeX (ext:optimize-interface (safety 3)))
994 LaTeX ;; with-array-data will get us to the actual data. However, because
995 LaTeX ;; the array could have been displaced, we need to know where the
996 LaTeX ;; data starts.
997 LaTeX (lisp::with-array-data ((data array)
1000 LaTeX (declare (ignore end))
1001 LaTeX ;; DATA is a specialized simple-array. Memory is laid out like this:
1003 LaTeX ;; byte offset Value
1004 LaTeX ;; 0 type code (should be 70 for double-float vector)
1005 LaTeX ;; 4 4 * number of elements in vector
1006 LaTeX ;; 8 1st element of vector
1009 LaTeX (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
1010 LaTeX (type-size (let ((type (array-element-type data)))
1011 LaTeX (cond ((or (equal type '(signed-byte 8))
1012 LaTeX (equal type '(unsigned-byte 8)))
1014 LaTeX ((or (equal type '(signed-byte 16))
1015 LaTeX (equal type '(unsigned-byte 16)))
1017 LaTeX ((or (equal type '(signed-byte 32))
1018 LaTeX (equal type '(unsigned-byte 32)))
1020 LaTeX ((equal type 'single-float)
1022 LaTeX ((equal type 'double-float)
1025 LaTeX (error "Unknown specialized array element type"))))))
1026 LaTeX (declare (type (unsigned-byte 32) addr)
1027 LaTeX (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
1028 LaTeX (system:int-sap (the (unsigned-byte 32)
1029 LaTeX (+ addr (* type-size start)))))))
1032 LaTeX Assume we have the C function below that we wish to use:
1033 LaTeX \begin{example}
1034 LaTeX double dotprod(double* x, double* y, int n)
1037 LaTeX double sum = 0;
1039 LaTeX for (k = 0; k < n; ++k) \{
1040 LaTeX sum += x[k] * y[k];
1044 LaTeX The following example generates two large arrays in Lisp, and calls the C
1045 LaTeX function to do the desired computation. This would not have been
1046 LaTeX possible using \code{malloc} or \code{make-alien} since we need about
1047 LaTeX 16 MB of memory to hold the two arrays.
1048 LaTeX \begin{example}
1049 LaTeX (define-alien-routine "dotprod" double
1050 LaTeX (x (* double-float) :in)
1051 LaTeX (y (* double-float) :in)
1054 LaTeX (let ((x (make-array 1000000 :element-type 'double-float))
1055 LaTeX (y (make-array 1000000 :element-type 'double-float)))
1056 LaTeX ;; Initialize X and Y somehow
1057 LaTeX (let ((x-addr (system:int-sap (array-data-address x)))
1058 LaTeX (y-addr (system:int-sap (array-data-address y))))
1059 LaTeX (dotprod x-addr y-addr 1000000)))
1061 LaTeX In this example, it may be useful to wrap the inner \code{let}
1062 LaTeX expression in an \code{unwind-protect} that first turns off garbage
1063 LaTeX collection and then turns garbage collection on afterwards. This will
1064 LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
1065 LaTeX have obtained the (now erroneous) addresses but before the call to
1066 LaTeX \code{dotprod} is made.
1072 <sect1><title>Step-By-Step Example of the Foreign Function Interface</>
1075 This section presents a complete example of an interface to a somewhat
1076 complicated C function.
1080 Suppose you have the following C function which you want to be able to
1081 call from Lisp in the file <filename>test.c</>
1089 struct c_struct *c_function (i, s, r, a)
1096 struct c_struct *r2;
1098 printf("i = %d\n", i);
1099 printf("s = %s\n", s);
1100 printf("r->x = %d\n", r->x);
1101 printf("r->s = %s\n", r->s);
1102 for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
1103 r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
1105 r2->s = "a C string";
1111 It is possible to call this C function from Lisp using the file
1112 <filename>test.lisp</> containing
1114 (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
1115 (cl:in-package "TEST-C-CALL")
1117 ;;; Define the record C-STRUCT in Lisp.
1118 (define-alien-type nil
1123 ;;; Define the Lisp function interface to the C routine. It returns a
1124 ;;; pointer to a record of type C-STRUCT. It accepts four parameters:
1125 ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
1126 ;;; record; and A, a pointer to the array of 10 ints.
1128 ;;; The INLINE declaration eliminates some efficiency notes about heap
1129 ;;; allocation of alien values.
1130 (declaim (inline c-function))
1131 (define-alien-routine c-function
1132 (* (struct c-struct))
1135 (r (* (struct c-struct)))
1138 ;;; a function which sets up the parameters to the C function and
1139 ;;; actually calls it
1141 (with-alien ((ar (array int 10))
1142 (c-struct (struct c-struct)))
1143 (dotimes (i 10) ; Fill array.
1144 (setf (deref ar i) i))
1145 (setf (slot c-struct 'x) 20)
1146 (setf (slot c-struct 's) "a Lisp string")
1148 (with-alien ((res (* (struct c-struct))
1149 (c-function 5 "another Lisp string" (addr c-struct) ar)))
1150 (format t "~&back from C function~%")
1151 (multiple-value-prog1
1152 (values (slot res 'x)
1155 ;; Deallocate result. (after we are done referring to it:
1156 ;; "Pillage, *then* burn.")
1157 (free-alien res)))))</programlisting>
1161 To execute the above example, it is necessary to compile the C routine,
1163 <userinput>cc -c test.c</>
1164 (In order to enable incremental loading with some linkers, you may need
1166 <userinput>cc -G 0 -c test.c</>)
1170 Once the C code has been compiled, you can start up Lisp and load it in:
1172 Lisp should start up with its normal prompt.</para>
1176 compile the Lisp file. (This step can be done separately. You don't
1177 have to recompile every time.)
1178 <userinput>(compile-file "test.lisp")</>
1181 Within Lisp, load the foreign object file to define the necessary
1183 <userinput>(load-foreign "test.o")</>.
1184 This must be done before loading any code that refers
1189 Now you can load the compiled Lisp ("fasl") file into Lisp:
1190 <userinput>(load "test.fasl")</>
1191 And once the Lisp file is loaded, you can call the
1192 Lisp routine that sets up the parameters and calls the C
1194 <userinput>(test-c-call::call-cfun)</>
1198 The C routine should print the following information to standard output:
1199 <!-- FIXME: What should be here is a verbatim environment for computer
1200 output, but since I don't know one in DocBook, I made do with
1201 PROGRAMLISTING for now... -->
1202 <programlisting>i = 5
1203 s = another Lisp string
1205 r->s = a Lisp string
1215 a[9] = 9.</programlisting>
1216 After return from the C function,
1217 the Lisp wrapper function should print the following output:
1218 <programlisting>back from C function</programlisting>
1219 And upon return from the Lisp wrapper function,
1220 before the next prompt is printed, the
1221 Lisp read-eval-print loop should print the following return values:
1222 <!-- FIXME: As above, it's not a program listing, but computer output... -->