1 This chapter describes SBCL's interface to C programs and
2 libraries (and, since C interfaces are a sort of @emph{ingua
3 franca} of the Unix world, to other programs and libraries in
7 Note: In the modern Lisp world, the usual term for this functionality
8 is Foreign Function Interface, or @acronym{FFI}, where despite the
9 mention of ``function'' in this term, @acronym{FFI} also
10 refers to direct manipulation of C data structures as well as
11 functions. The traditional CMUCL terminology is Alien Interface, and
12 while that older terminology is no longer used much in the system
13 documentation, it still reflected in names in the implementation,
14 notably in the name of the @code{SB-ALIEN} package.
18 * Introduction to the Foreign Function Interface::
20 * Operations On Foreign Values::
22 * Foreign Data Structure Examples::
23 * Loading Unix Object Files::
24 * Foreign Function Calls::
25 * Step-By-Step Example of the Foreign Function Interface::
28 @node Introduction to the Foreign Function Interface
29 @comment node-name, next, previous, up
30 @section Introduction to the Foreign Function Interface
31 @c AKA "Introduction to Aliens" in the CMU CL manual
33 Because of Lisp's emphasis on dynamic memory allocation and garbage
34 collection, Lisp implementations use non-C-like memory representations
35 for objects. This representation mismatch creates friction when a Lisp
36 program must share objects with programs which expect C data. There
37 are three common approaches to establishing communication:
41 The burden can be placed on the foreign program (and programmer) by
42 requiring the knowledge and use of the representations used internally
43 by the Lisp implementation. This can require a considerable amount of
44 ``glue'' code on the C side, and that code tends to be sensitively
45 dependent on the internal implementation details of the Lisp system.
48 The Lisp system can automatically convert objects back and forth
49 between the Lisp and foreign representations. This is convenient, but
50 translation becomes prohibitively slow when large or complex data
51 structures must be shared. This approach is supported by the SBCL
52 @acronym{FFI}, and used automatically by the when passing integers and
56 The Lisp program can directly manipulate foreign objects through the
57 use of extensions to the Lisp language.
61 SBCL, like CMUCL before it, relies primarily on the automatic
62 conversion and direct manipulation approaches. The @code{SB-ALIEN}
63 package provices a facility wherein foreign values of simple scalar
64 types are automatically converted and complex types are directly
65 manipulated in their foreign representation. Additionally the
66 lower-level System Area Pointers (or @acronym{SAP}s) can be used where
67 necessary to provide untyped access to foreign memory.
69 Any foreign objects that can't automatically be converted into Lisp
70 values are represented by objects of type @code{alien-value}. Since
71 Lisp is a dynamically typed language, even foreign objects must have a
72 run-time type; this type information is provided by encapsulating the
73 raw pointer to the foreign data within an @code{alien-value} object.
75 The type language and operations on foreign types are
76 intentionally similar to those of the C language.
79 @comment node-name, next, previous, up
80 @section Foreign Types
81 @c AKA "Alien Types" in the CMU CL manual
83 Alien types have a description language based on nested list
84 structure. For example the C type
93 has the corresponding SBCL @acronym{FFI} type
98 (b (array (* (struct foo)) 100)))
103 * Defining Foreign Types::
104 * Foreign Types and Lisp Types::
105 * Foreign Type Specifiers::
108 @node Defining Foreign Types
109 @comment node-name, next, previous, up
110 @subsection Defining Foreign Types
112 Types may be either named or anonymous. With structure and union
113 types, the name is part of the type specifier, allowing recursively
114 defined types such as:
117 (struct foo (a (* (struct foo))))
120 An anonymous structure or union type is specified by using the name
121 @code{nil}. The @code{with-alien} macro defines a local scope which
122 ``captures'' any named type definitions. Other types are not
123 inherently named, but can be given named abbreviations using the
124 @code{define-alien-type} macro.
126 @node Foreign Types and Lisp Types
127 @comment node-name, next, previous, up
128 @subsection Foreign Types and Lisp Types
130 The foreign types form a subsystem of the SBCL type system. An
131 @code{alien} type specifier provides a way to use any foreign type as a
132 Lisp type specifier. For example,
135 (typep @var{foo} '(alien (* int)))
138 can be used to determine whether @var{foo} is a pointer to a foreign
139 @code{int}. @code{alien} type specifiers can be used in the same ways
140 as ordinary Lisp type specifiers (like @code{string}.) Alien type
141 declarations are subject to the same precise type checking as any
142 other declaration. @xref{Precise Type Checking}.
144 Note that the type identifiers used in the foreign type system overlap
145 with native Lisp type specifiers in some cases. For example, the type
146 specifier @code{(alien single-float)} is identical to
147 @code{single-float}, since foreign floats are automatically converted
148 to Lisp floats. When @code{type-of} is called on an alien value that
149 is not automatically converted to a Lisp value, then it will return an
150 @code{alien} type specifier.
152 @node Foreign Type Specifiers
153 @comment node-name, next, previous, up
154 @subsection Foreign Type Specifiers
156 Note: All foreign type names are exported from the @code{sb-alien}
157 package. Some foreign type names are also symbols in
158 the @code{common-lisp} package, in which case they are
159 reexported from the @code{sb-alien} package, so that
160 e.g. it is legal to refer to @code{sb-alien:single-float}.
162 These are the basic foreign type specifiers:
166 The foreign type specifier @code{(* @var{foo})} describes a pointer to
167 an object of type @var{foo}. A pointed-to type @var{foo} of @code{t}
168 indicates a pointer to anything, similar to @code{void *} in
169 ANSI C. A null alien pointer can be detected with the
170 @code{sb-alien:null-alien} function.
173 The foreign type specifier @code{(array @var{foo} &rest
174 dimensions)} describes array of the specified @code{dimensions},
175 holding elements of type @var{foo}. Note that (unlike in C) @code{(*
176 @var{foo})} and @code{(array @var{foo})} are considered to be
177 different types when type checking is done. If equivalence of pointer
178 and array types is desired, it may be explicitly coerced using
179 @code{sb-alien:cast}.
181 Arrays are accessed using @code{sb-alien:deref}, passing the indices
182 as additional arguments. Elements are stored in column-major order
183 (as in C), so the first dimension determines only the size of the
184 memory block, and not the layout of the higher dimensions. An array
185 whose first dimension is variable may be specified by using @code{nil}
186 as the first dimension. Fixed-size arrays can be allocated as array
187 elements, structure slots or @code{sb-alien:with-alien}
188 variables. Dynamic arrays can only be allocated using
189 @code{sb-alien:make-alien}.
192 The foreign type specifier @code{(sb-alien:struct @var{name} &rest
193 @var{fields})} describes a structure type with the specified
194 @var{name} and @var{fields}. Fields are allocated at the same offsets
195 used by the implementation's C compiler. If @var{name} is @code{nil}
196 then the structure is anonymous.
198 If a named foreign @code{struct} specifier is passed to
199 @code{define-alien-type} or @code{with-alien}, then this defines,
200 respectively, a new global or local foreign structure type. If no
201 @var{fields} are specified, then the fields are taken
202 from the current (local or global) alien structure type definition of
206 The foreign type specifier @code{(sb-alien:union @var{name} &rest
207 @var{fields})} is similar to @code{sb-alien:struct}, but describes a
208 union type. All fields are allocated at the same offset, and the size
209 of the union is the size of the largest field. The programmer must
210 determine which field is active from context.
213 The foreign type specifier @code{(sb-alien:enum @var{name} &rest
214 @var{specs})} describes an enumeration type that maps between integer
215 values and keywords. If @var{name} is @code{nil}, then the type is
216 anonymous. Each element of the @var{specs} list is either a Lisp
217 keyword, or a list @code{(@var{keyword} @var{value})}. @var{value} is
218 an integer. If @var{value} is not supplied, then it defaults to one
219 greater than the value for the preceding spec (or to zero if it is the
223 The foreign type specifier @code{(sb-alien:signed &optional
224 @var{bits})} specifies a signed integer with the specified number of
225 @var{bits} precision. The upper limit on integer
226 precision is determined by the machine's word size. If
227 @var{bits} is not specified, the maximum size will be
231 The foreign type specifier @code{(integer &optional @var{bits})}
232 is equivalent to the corresponding type specifier using
233 @code{sb-alien:signed} instead of @code{integer}.
236 The foreign type specifier @code{(sb-alien:unsigned &optional
237 @var{bits})} is like corresponding type specifier using
238 @code{sb-alien:signed} except that the variable is treated as an
242 The foreign type specifier @code{(boolean &optional @var{bits})} is
243 similar to an enumeration type, but maps from Lisp @code{nil} and
244 @code{t} to C @code{0} and @code{1} respectively. @var{bits}
245 determines the amount of storage allocated to hold the truth value.
248 The foreign type specifier @code{single-float} describes a
249 floating-point number in IEEE single-precision format.
252 The foreign type specifier @code{double-float} describes a
253 floating-point number in IEEE double-precision format.
256 The foreign type specifier @code{(function @var{result-type} &rest
257 @var{arg-types})} describes a foreign function that takes arguments of
258 the specified @var{arg-types} and returns a result of type
259 @var{result-type}. Note that the only context where a foreign
260 @code{function} type is directly specified is in the argument to
261 @code{sb-alien:alien-funcall}. In all other contexts, foreign
262 functions are represented by foreign function pointer types: @code{(*
263 (function @dots{}))}.
266 The foreign type specifier @code{sb-alien:system-area-pointer}
267 describes a pointer which is represented in Lisp as a
268 @code{system-area-pointer} object. SBCL exports this type from
269 @code{sb-alien} because CMUCL did, but tentatively (as of the first
270 draft of this section of the manual, SBCL 0.7.6) it is deprecated,
271 since it doesn't seem to be required by user code.
274 The foreign type specifier @code{sb-alien:void} is used in function
275 types to declare that no useful value is returned. Using
276 @code{alien-funcall} to call a @code{void} foreign function will
280 The foreign type specifier @code{sb-alien:c-string} is similar to
281 @code{(* char)}, but is interpreted as a null-terminated string, and
282 is automatically converted into a Lisp string when accessed; or if the
283 pointer is C @code{NULL} or @code{0}, then accessing it gives Lisp
284 @code{nil}. Lisp strings are stored with a trailing NUL
285 termination, so no copying (either by the user or the implementation)
286 is necessary when passing them to foreign code.
288 Assigning a Lisp string to a @code{c-string} structure field or
289 variable stores the contents of the string to the memory already
290 pointed to by that variable. When a foreign object of type @code{(*
291 char)} is assigned to a @code{c-string}, then the
292 @code{c-string} pointer is assigned to. This allows
293 @code{c-string} pointers to be initialized. For example:
296 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
298 (define-alien-type nil (struct foo (str c-string)))
300 (defun make-foo (str)
301 (let ((my-foo (make-alien (struct foo))))
302 (setf (slot my-foo 'str) (make-alien char (length str))
303 (slot my-foo 'str) str)
307 Storing Lisp @code{NIL} in a @code{c-string} writes C @code{NULL} to
311 @code{sb-alien} also exports translations of these C type
312 specifiers as foreign type specifiers: @code{sb-alien:char},
313 @code{sb-alien:short}, @code{sb-alien:int},
314 @code{sb-alien:long}, @code{sb-alien:unsigned-char},
315 @code{sb-alien:unsigned-short},
316 @code{sb-alien:unsigned-int},
317 @code{sb-alien:unsigned-long}, @code{sb-alien:float}, and
318 @code{sb-alien:double}.
322 @node Operations On Foreign Values
323 @comment node-name, next, previous, up
324 @section Operations On Foreign Values
325 @c AKA "Alien Operations" in the CMU CL manual
327 This section describes how to read foreign values as Lisp values, how
328 to coerce foreign values to different kinds of foreign values, and how
329 to dynamically allocate and free foreign variables.
332 * Accessing Foreign Values::
333 * Coercing Foreign Values::
334 * Foreign Dynamic Allocation::
337 @node Accessing Foreign Values
338 @comment node-name, next, previous, up
339 @subsection Accessing Foreign Values
341 @defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
344 The @code{sb-alien:deref} function returns the value pointed to by a
345 foreign pointer, or the value of a foreign array element. When
346 dereferencing a pointer, an optional single index can be specified to
347 give the equivalent of C pointer arithmetic; this index is scaled by
348 the size of the type pointed to. When dereferencing an array, the
349 number of indices must be the same as the number of dimensions in the
350 array type. @code{deref} can be set with @code{setf} to assign a new
354 @defun sb-alien:slot @var{struct-or-union} &rest @var{slot-names}
357 The @code{sb-alien:slot} function extracts the value of the slot named
358 @var{slot-name} from a foreign @code{struct} or @code{union}. If
359 @var{struct-or-union} is a pointer to a structure or union, then it is
360 automatically dereferenced. @code{sb-alien:slot} can be set with
361 @code{setf} to assign a new value. Note that @var{slot-name} is
362 evaluated, and need not be a compile-time constant (but only constant
363 slot accesses are efficiently compiled).
367 @subsubsection Untyped memory
369 As noted at the beginning of the chapter, the System Area Pointer
370 facilities allow untyped access to foreign memory. @acronym{SAP}s can
371 be converted to and from the usual typed foreign values using
372 @code{sap-alien} and @code{alien-sap} (described elsewhere), and also
373 to and from integers - raw machine addresses. They should thus be
374 used with caution; corrupting the Lisp heap or other memory with
375 @acronym{SAP}s is trivial.
377 @defun sb-sys:int-sap @var{machine-address}
380 Creates a @acronym{SAP} pointing at the virtual address
381 @var{machine-address}.
384 @defun sb-sys:sap-ref-32 @var{sap} @var{offset}
387 Access the value of the memory location at @var{offset} bytes from
388 @var{sap}. This form may also be used with @code{setf} to alter the
389 memory at that location.
392 @defun sb-sys:sap= @var{sap1} @var{sap2}
395 Compare @var{sap1} and @var{sap2} for equality.
398 Similarly named functions exist for accessing other sizes of word,
399 other comparisons, and other conversions. The reader is invited to
400 use @code{apropos} and @code{describe} for more details
403 (apropos "sap" :sb-sys)
407 @node Coercing Foreign Values
408 @comment node-name, next, previous, up
409 @subsection Coercing Foreign Values
411 @defun sb-alien:addr @var{alien-expr}
414 The @code{sb-alien:addr} macro returns a pointer to the location
415 specified by @var{alien-expr}, which must be either a foreign
416 variable, a use of @code{sb-alien:deref}, a use of
417 @code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
420 @defun sb-alien:cast @var{foreign-value} @var{new-type}
423 The @code{sb-alien:cast} macro converts @var{foreign-value} to a new
424 foreign value with the specified @var{new-type}. Both types, old and
425 new, must be foreign pointer, array or function types. Note that the
426 resulting Lisp foreign variable object is not @code{eq} to the
427 argument, but it does refer to the same foreign data bits.
430 @defun sb-alien:sap-alien @var{sap} @var{type}
433 The @code{sb-alien:sap-alien} function converts @var{sap} (a system
434 area pointer) to a foreign value with the specified
435 @var{type}. @var{type} is not evaluated. </para>
437 The @var{type} must be some foreign pointer, array, or record type.
440 @defun sb-alien:alien-sap @var{foreign-value} @var{type}
443 The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
444 points to @var{alien-value}'s data.
446 The @var{foreign-value} must be of some foreign pointer, array, or
451 @node Foreign Dynamic Allocation
452 @comment node-name, next, previous, up
453 @subsection Foreign Dynamic Allocation
455 Lisp code can call the C standard library functions @code{malloc} and
456 @code{free} to dynamically allocate and deallocate foreign
457 variables. The Lisp code shares the same allocator with foreign C
458 code, so it's OK for foreign code to call @code{free} on the result of
459 Lisp @code{sb-alien:make-alien}, or for Lisp code to call
460 @code{sb-alien:free-alien} on foreign objects allocated by C
463 @defmac sb-alien:make-alien @var{type} @var{size}
466 The @code{sb-alien:make-alien} macro
467 returns a dynamically allocated foreign value of the specified
468 @var{type} (which is not evaluated.) The allocated memory is not
469 initialized, and may contain arbitrary junk. If supplied,
470 @var{size} is an expression to evaluate to compute the size of the
471 allocated object. There are two major cases:
475 When @var{type} is a foreign array type, an array of that type is
476 allocated and a pointer to it is returned. Note that you must use
477 @code{deref} to change the result to an array before you can use
478 @code{deref} to read or write elements:
481 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
482 (defvar *foo* (make-alien (array char 10)))
483 (type-of *foo*) @result{} (alien (* (array (signed 8) 10)))
484 (setf (deref (deref foo) 0) 10) @result{} 10
487 If supplied, @var{size} is used as the first dimension for the
491 When @var{type} is any other foreign type, then an object for that
492 type is allocated, and a pointer to it is returned. So
493 @code{(make-alien int)} returns a @code{(* int)}. If @var{size} is
494 specified, then a block of that many objects is allocated, with the
495 result pointing to the first one.
501 @defun sb-alien:free-alien @var{foreign-value}
504 The @code{sb-alien:free-alien} function
505 frees the storage for @var{foreign-value},
506 which must have been allocated with Lisp @code{make-alien}
509 See also the @code{sb-alien:with-alien} macro, which allocates foreign
513 @node Foreign Variables
514 @comment node-name, next, previous, up
515 @section Foreign Variables
516 @c AKA "Alien Variables" in the CMU CL manual
518 Both local (stack allocated) and external (C global) foreign variables
522 * Local Foreign Variables::
523 * External Foreign Variables::
526 @node Local Foreign Variables
527 @comment node-name, next, previous, up
528 @subsection Local Foreign Variables
530 @defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
533 The @code{with-alien} macro establishes local foreign variables with
534 the specified alien types and names. This form is analogous to
535 defining a local variable in C: additional storage is allocated, and
536 the initial value is copied. This form is less analogous to
537 @code{LET}-allocated Lisp variables, since the variables can't be
538 captured in closures: they live only for the dynamic extent of the
539 body, and referring to them outside is a gruesome error.
541 The @var{var-definitions} argument is a list of
542 variable definitions, each of the form
544 (@var{name} @var{type} &optional @var{initial-value})
547 The names of the variables are established as symbol-macros; the
548 bindings have lexical scope, and may be assigned with @code{setq} or
551 The @code{with-alien} macro also establishes a new scope for named
552 structures and unions. Any @var{type} specified for a variable may
553 contain named structure or union types with the slots specified.
554 Within the lexical scope of the binding specifiers and body, a locally
555 defined foreign structure type @var{foo} can be referenced by its name
556 using @code{(struct @var{foo})}.
559 @node External Foreign Variables
560 @comment node-name, next, previous, up
561 @subsection External Foreign Variables
563 External foreign names are strings, and Lisp names are symbols. When
564 an external foreign value is represented using a Lisp variable, there
565 must be a way to convert from one name syntax into the other. The
566 macros @code{extern-alien}, @code{define-alien-variable} and
567 @code{define-alien-routine} use this conversion heuristic:
572 Alien names are converted to Lisp names by uppercasing and replacing
573 underscores with hyphens.
576 Conversely, Lisp names are converted to alien names by lowercasing and
577 replacing hyphens with underscores.
580 Both the Lisp symbol and alien string names may be separately
581 specified by using a list of the form
584 (alien-string lisp-symbol)
589 @defmac sb-alien:define-alien-variable @var{name} @var{type}
590 @findex define-alien-variable
592 The @code{define-alien-variable} macro defines @var{name} as an
593 external foreign variable of the specified foreign @code{type}.
594 @var{name} and @code{type} are not evaluated. The Lisp name of the
595 variable (see above) becomes a global alien variable. Global alien
596 variables are effectively ``global symbol macros''; a reference to the
597 variable fetches the contents of the external variable. Similarly,
598 setting the variable stores new contents -- the new contents must be
599 of the declared @code{type}. Someday, they may well be implemented
600 using the @acronym{ANSI} @code{define-symbol-macro} mechanism, but as
601 of SBCL 0.7.5, they are still implemented using an older more-or-less
602 parallel mechanism inherited from CMUCL.
604 For example, to access a C-level counter @var{foo}, one could write
607 (define-alien-variable "foo" int)
608 ;; Now it is possible to get the value of the C variable foo simply by
609 ;; referencing that Lisp variable:
616 @defun sb-alien:get-errno
619 Since in modern C libraries, the @code{errno} ``variable'' is typically
620 no longer a variable, but some bizarre artificial construct
621 which behaves superficially like a variable within a given thread,
622 it can no longer reliably be accessed through the ordinary
623 @code{define-alien-variable} mechanism. Instead, SBCL provides
624 the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
627 @defmac sb-alien:extern-alien @var{name} @var{type}
630 The @code{extern-alien} macro returns an alien with the specified
631 @var{type} which points to an externally defined value. @var{name} is
632 not evaluated, and may be either a string or a symbol. @var{type} is
633 an unevaluated alien type specifier.
636 @node Foreign Data Structure Examples
637 @comment node-name, next, previous, up
638 @section Foreign Data Structure Examples
639 @c AKA "Alien Data Structure Example" in the CMU CL manual
641 Now that we have alien types, operations and variables, we can
642 manipulate foreign data structures. This C declaration
651 can be translated into the following alien type:
654 (define-alien-type nil
657 (b (array (* (struct foo)) 100))))
660 Once the @code{foo} alien type has been defined as above, the C
668 can be translated in this way:
671 (with-alien ((f (struct foo)))
672 (slot (deref (slot f 'b) 7) 'a)
674 ;; Do something with f...
678 Or consider this example of an external C variable and some accesses:
687 extern struct c_struct *my_struct;
690 my_struct = my_struct->n;
693 which can be manipulated in Lisp like this:
696 (define-alien-type nil
704 (define-alien-variable "my_struct" (* c-struct))
705 (incf (slot my-struct 'x))
706 (setf (slot my-struct 'a) 5)
707 (setq my-struct (slot my-struct 'n))
710 @node Loading Unix Object Files
711 @comment node-name, next, previous, up
712 @section Loading Unix Object Files
714 Foreign object files can be loaded into the running Lisp process by
715 calling @code{load-shared-object}.
717 The @code{sb-alien:load-shared-object} loads a single object file into
718 the currently running Lisp. The external symbols defining routines and
719 variables are made available for future external references (e.g. by
720 @code{extern-alien}). Forward references to foreign symbols aren't
721 supported: @code{load-shared-object} must be run before any of the
722 defined symbols are referenced.
725 Note: As of SBCL 0.7.5, all foreign code (code loaded with
726 @code{load-shared-object}) is lost when a Lisp
727 core is saved with @code{sb-ext:save-lisp-and-die}, and no attempt is
728 made to restore it when the core is loaded. Historically this has been
729 an annoyance both for SBCL users and for CMUCL users. It's hard to
730 solve this problem completely cleanly, but some generally-reliable
731 partial solution might be useful. Once someone in either camp gets
732 sufficiently annoyed to create it, SBCL is likely to adopt some
733 mechanism for automatically restoring foreign code when a saved core
738 @node Foreign Function Calls
739 @comment node-name, next, previous, up
740 @section Foreign Function Calls
742 The foreign function call interface allows a Lisp program to call
743 many functions written in languages that use the C calling convention.
745 Lisp sets up various signal handling routines and other environment
746 information when it first starts up, and expects these to be in place
747 at all times. The C functions called by Lisp should not change the
748 environment, especially the signal handlers: the signal handlers
749 installed by Lisp typically have interesting flags set (e.g to request
750 machine context information, or for signal delivery on an alternate
751 stack) which the Lisp runtime relies on for correct operation.
752 Precise details of how this works may change without notice between
753 versions; the source, or the brain of a friendly SBCL developer, is
754 the only documentation. Users of a Lisp built with the
755 @code{:sb-thread} feature should also read the section about threads,
759 * The alien-funcall Primitive::
760 * The define-alien-routine Macro::
761 * define-alien-routine Example::
762 * Calling Lisp From C::
765 @node The alien-funcall Primitive
766 @comment node-name, next, previous, up
767 @subsection The @code{alien-funcall} Primitive
769 @defun sb-alien:alien-funcall @var{alien-function} &rest @var{arguments}
770 @findex alien-funcall
772 The @code{alien-funcall} function is the foreign function call
773 primitive: @var{alien-function} is called with the supplied
774 @var{arguments} and its C return value is returned as a Lisp value.
775 The @var{alien-function} is an arbitrary run-time expression; to refer
776 to a constant function, use @code{extern-alien} or a value defined by
777 @code{define-alien-routine}.
779 The type of @code{alien-function} must be @code{(alien (function
780 ...))} or @code{(alien (* (function ...)))}. The function type is
781 used to determine how to call the function (as though it was declared
782 with a prototype.) The type need not be known at compile time, but
783 only known-type calls are efficiently compiled. Limitations:
788 Structure type return values are not implemented.
791 Passing of structures by value is not implemented.
797 Here is an example which allocates a @code{(struct foo)}, calls a
798 foreign function to initialize it, then returns a Lisp vector of all
799 the @code{(* (struct foo))} objects filled in by the foreign call:
802 ;; Allocate a foo on the stack.
803 (with-alien ((f (struct foo)))
804 ;; Call some C function to fill in foo fields.
805 (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
807 ;; Find how many foos to use by getting the A field.
808 (let* ((num (slot f 'a))
809 (result (make-array num)))
810 ;; Get a pointer to the array so that we don't have to keep extracting it:
811 (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
812 ;; Loop over the first N elements and stash them in the result vector.
814 (setf (svref result i) (deref (deref a) i)))
819 @node The define-alien-routine Macro
820 @comment node-name, next, previous, up
821 @subsection The @code{define-alien-routine} Macro
823 @defmac sb-alien:define-alien-routine @var{name} @var{result-type} &rest @var{arg-specifiers}
824 @findex define-alien-routine
826 The @code{define-alien-routine} macro is a convenience for
827 automatically generating Lisp interfaces to simple foreign functions.
828 The primary feature is the parameter style specification, which
829 translates the C pass-by-reference idiom into additional return
832 @var{name} is usually a string external symbol, but may also be a
833 symbol Lisp name or a list of the foreign name and the Lisp name. If
834 only one name is specified, the other is automatically derived as for
835 @code{extern-alien}. @var{result-type} is the alien type of the
838 Each element of the @var{arg-specifiers} list
839 specifies an argument to the foreign function, and is
842 (aname atype &optional style)
845 @var{aname} is the symbol name of the argument to the constructed
846 function (for documentation). @var{atype} is the alien type of
847 corresponding foreign argument. The semantics of the actual call are
848 the same as for @code{alien-funcall}. @var{style} specifies how this
849 argument should be handled at call and return time, and should be one
855 @code{:in} specifies that the argument is passed by value. This is the
856 default. @code{:in} arguments have no corresponding return value from
860 @code{:copy} is similar to @code{:in}, but the argument is copied to a
861 pre-allocated object and a pointer to this object is passed to the
865 @code{:out} specifies a pass-by-reference output value. The type of
866 the argument must be a pointer to a fixed-sized object (such as an
867 integer or pointer). @code{:out} and @code{:in-out} style cannot be
868 used with pointers to arrays, records or functions. An object of the
869 correct size is allocated on the stack, and its address is passed to
870 the foreign function. When the function returns, the contents of this
871 location are returned as one of the values of the Lisp function (and
872 the location is automatically deallocated).
875 @code{:in-out} is a combination of @code{:copy} and @code{:out}. The
876 argument is copied to a pre-allocated object and a pointer to this
877 object is passed to the foreign routine. On return, the contents of
878 this location is returned as an additional value.
883 Note: Any efficiency-critical foreign interface function should be inline
884 expanded, which can be done by preceding the
885 @code{define-alien-routine} call with:
888 (declaim (inline lisp-name))
891 In addition to avoiding the Lisp call overhead, this allows
892 pointers, word-integers and floats to be passed using non-descriptor
893 representations, avoiding consing.)
898 @node define-alien-routine Example
899 @comment node-name, next, previous, up
900 @subsection @code{define-alien-routine} Example
902 Consider the C function @code{cfoo} with the following calling
909 char *a; /* update */
912 /* body of cfoo(...) */
916 This can be described by the following call to
917 @code{define-alien-routine}:
920 (define-alien-routine "cfoo" void
926 The Lisp function @code{cfoo} will have two arguments (@var{str} and
927 @var{a}) and two return values (@var{a} and @var{i}).
929 @node Calling Lisp From C
930 @comment node-name, next, previous, up
931 @subsection Calling Lisp From C
933 Calling Lisp functions from C is sometimes possible, but is extremely
934 hackish and poorly supported as of SBCL 0.7.5. See @code{funcall0}
935 @dots{} @code{funcall3} in the runtime system. The arguments must be
936 valid SBCL object descriptors (so that e.g. fixnums must be
937 left-shifted by 2.) As of SBCL 0.7.5, the format of object descriptors
938 is documented only by the source code and, in parts, by the old CMUCL
939 @file{INTERNALS} documentation.
941 Note that the garbage collector moves objects, and won't be
942 able to fix up any references in C variables. There are three
943 mechanisms for coping with this:
947 The @code{sb-ext:purify} moves all live Lisp
948 data into static or read-only areas such that it will never be moved
949 (or freed) again in the life of the Lisp session
952 @code{sb-sys:with-pinned-objects} is a macro which arranges for some
953 set of objects to be pinned in memory for the dynamic extent of its
954 body forms. On ports which use the generational garbage collector (as
955 of SBCL 0.8.3, only the x86) this has a page granularity - i.e. the
956 entire 4k page or pages containing the objects will be locked down. On
957 other ports it is implemented by turning off GC for the duration (so
958 could be said to have a whole-world granularity).
961 Disable GC, using the @code{without-gcing} macro or @code{gc-off}
965 @c <!-- FIXME: This is a "changebar" section from the CMU CL manual.
966 @c I (WHN 2002-07-14) am not very familiar with this content, so
967 @c I'm not immediately prepared to try to update it for SBCL, and
968 @c I'm not feeling masochistic enough to work to encourage this
969 @c kind of low-level hack anyway. However, I acknowledge that callbacks
970 @c are sometimes really really necessary, so I include the original
971 @c text in case someone is hard-core enough to benefit from it. If
972 @c anyone brings the information up to date for SBCL, it belong
973 @c either in the main manual or on a CLiki SBCL Internals page.
974 @c LaTeX \subsection{Accessing Lisp Arrays}
976 @c LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
977 @c LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
978 @c LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
979 @c LaTeX use and this memory is typically about 8 MB above the start of the C
980 @c LaTeX heap. Thus, only about 8 MB of memory can be dynamically
981 @c LaTeX allocated.}.
983 @c Empirically determined to be considerably >8Mb on this x86 linux
984 @c machine, but I don't know what the actual values are - dan 2003.09.01
986 @c Note that this technique is used in SB-GROVEL in the SBCL contrib
989 @c LaTeX To overcome this limitation, it is possible to access the content of
990 @c LaTeX Lisp arrays which are limited only by the amount of physical memory
991 @c LaTeX and swap space available. However, this technique is only useful if
992 @c LaTeX the foreign function takes pointers to memory instead of allocating
993 @c LaTeX memory for itself. In latter case, you will have to modify the
994 @c LaTeX foreign functions.
996 @c LaTeX This technique takes advantage of the fact that \cmucl{} has
997 @c LaTeX specialized array types (\pxlref{specialized-array-types}) that match
998 @c LaTeX a typical C array. For example, a \code{(simple-array double-float
999 @c LaTeX (100))} is stored in memory in essentially the same way as the C
1000 @c LaTeX array \code{double x[100]} would be. The following function allows us
1001 @c LaTeX to get the physical address of such a Lisp array:
1002 @c LaTeX \begin{example}
1003 @c LaTeX (defun array-data-address (array)
1004 @c LaTeX "Return the physical address of where the actual data of an array is
1007 @c LaTeX ARRAY must be a specialized array type in CMU Lisp. This means ARRAY
1008 @c LaTeX must be an array of one of the following types:
1010 @c LaTeX double-float
1011 @c LaTeX single-float
1012 @c LaTeX (unsigned-byte 32)
1013 @c LaTeX (unsigned-byte 16)
1014 @c LaTeX (unsigned-byte 8)
1015 @c LaTeX (signed-byte 32)
1016 @c LaTeX (signed-byte 16)
1017 @c LaTeX (signed-byte 8)
1019 @c LaTeX (declare (type (or #+signed-array (array (signed-byte 8))
1020 @c LaTeX #+signed-array (array (signed-byte 16))
1021 @c LaTeX #+signed-array (array (signed-byte 32))
1022 @c LaTeX (array (unsigned-byte 8))
1023 @c LaTeX (array (unsigned-byte 16))
1024 @c LaTeX (array (unsigned-byte 32))
1025 @c LaTeX (array single-float)
1026 @c LaTeX (array double-float))
1028 @c LaTeX (optimize (speed 3) (safety 0))
1029 @c LaTeX (ext:optimize-interface (safety 3)))
1030 @c LaTeX ;; with-array-data will get us to the actual data. However, because
1031 @c LaTeX ;; the array could have been displaced, we need to know where the
1032 @c LaTeX ;; data starts.
1033 @c LaTeX (lisp::with-array-data ((data array)
1036 @c LaTeX (declare (ignore end))
1037 @c LaTeX ;; DATA is a specialized simple-array. Memory is laid out like this:
1039 @c LaTeX ;; byte offset Value
1040 @c LaTeX ;; 0 type code (should be 70 for double-float vector)
1041 @c LaTeX ;; 4 4 * number of elements in vector
1042 @c LaTeX ;; 8 1st element of vector
1045 @c LaTeX (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
1046 @c LaTeX (type-size (let ((type (array-element-type data)))
1047 @c LaTeX (cond ((or (equal type '(signed-byte 8))
1048 @c LaTeX (equal type '(unsigned-byte 8)))
1050 @c LaTeX ((or (equal type '(signed-byte 16))
1051 @c LaTeX (equal type '(unsigned-byte 16)))
1053 @c LaTeX ((or (equal type '(signed-byte 32))
1054 @c LaTeX (equal type '(unsigned-byte 32)))
1056 @c LaTeX ((equal type 'single-float)
1058 @c LaTeX ((equal type 'double-float)
1061 @c LaTeX (error "Unknown specialized array element type"))))))
1062 @c LaTeX (declare (type (unsigned-byte 32) addr)
1063 @c LaTeX (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
1064 @c LaTeX (system:int-sap (the (unsigned-byte 32)
1065 @c LaTeX (+ addr (* type-size start)))))))
1066 @c LaTeX \end{example}
1068 @c LaTeX Assume we have the C function below that we wish to use:
1069 @c LaTeX \begin{example}
1070 @c LaTeX double dotprod(double* x, double* y, int n)
1073 @c LaTeX double sum = 0;
1075 @c LaTeX for (k = 0; k < n; ++k) \{
1076 @c LaTeX sum += x[k] * y[k];
1079 @c LaTeX \end{example}
1080 @c LaTeX The following example generates two large arrays in Lisp, and calls the C
1081 @c LaTeX function to do the desired computation. This would not have been
1082 @c LaTeX possible using \code{malloc} or \code{make-alien} since we need about
1083 @c LaTeX 16 MB of memory to hold the two arrays.
1084 @c LaTeX \begin{example}
1085 @c LaTeX (define-alien-routine "dotprod" double
1086 @c LaTeX (x (* double-float) :in)
1087 @c LaTeX (y (* double-float) :in)
1088 @c LaTeX (n int :in))
1090 @c LaTeX (let ((x (make-array 1000000 :element-type 'double-float))
1091 @c LaTeX (y (make-array 1000000 :element-type 'double-float)))
1092 @c LaTeX ;; Initialize X and Y somehow
1093 @c LaTeX (let ((x-addr (system:int-sap (array-data-address x)))
1094 @c LaTeX (y-addr (system:int-sap (array-data-address y))))
1095 @c LaTeX (dotprod x-addr y-addr 1000000)))
1096 @c LaTeX \end{example}
1097 @c LaTeX In this example, it may be useful to wrap the inner \code{let}
1098 @c LaTeX expression in an \code{unwind-protect} that first turns off garbage
1099 @c LaTeX collection and then turns garbage collection on afterwards. This will
1100 @c LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
1101 @c LaTeX have obtained the (now erroneous) addresses but before the call to
1102 @c LaTeX \code{dotprod} is made.
1107 @node Step-By-Step Example of the Foreign Function Interface
1108 @comment node-name, next, previous, up
1109 @section Step-By-Step Example of the Foreign Function Interface
1111 This section presents a complete example of an interface to a somewhat
1112 complicated C function.
1114 Suppose you have the following C function which you want to be able to
1115 call from Lisp in the file @file{test.c}
1124 struct c_struct *c_function (i, s, r, a)
1131 struct c_struct *r2;
1133 printf("i = %d\n", i);
1134 printf("s = %s\n", s);
1135 printf("r->x = %d\n", r->x);
1136 printf("r->s = %s\n", r->s);
1137 for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
1138 r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
1140 r2->s = "a C string";
1145 It is possible to call this C function from Lisp using the file
1146 @file{test.lisp} containing
1149 (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
1150 (cl:in-package "TEST-C-CALL")
1152 ;;; Define the record C-STRUCT in Lisp.
1153 (define-alien-type nil
1158 ;;; Define the Lisp function interface to the C routine. It returns a
1159 ;;; pointer to a record of type C-STRUCT. It accepts four parameters:
1160 ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
1161 ;;; record; and A, a pointer to the array of 10 ints.
1163 ;;; The INLINE declaration eliminates some efficiency notes about heap
1164 ;;; allocation of alien values.
1165 (declaim (inline c-function))
1166 (define-alien-routine c-function
1167 (* (struct c-struct))
1170 (r (* (struct c-struct)))
1173 ;;; a function which sets up the parameters to the C function and
1174 ;;; actually calls it
1176 (with-alien ((ar (array int 10))
1177 (c-struct (struct c-struct)))
1178 (dotimes (i 10) ; Fill array.
1179 (setf (deref ar i) i))
1180 (setf (slot c-struct 'x) 20)
1181 (setf (slot c-struct 's) "a Lisp string")
1183 (with-alien ((res (* (struct c-struct))
1184 (c-function 5 "another Lisp string" (addr c-struct) ar)))
1185 (format t "~&back from C function~%")
1186 (multiple-value-prog1
1187 (values (slot res 'x)
1190 ;; Deallocate result. (after we are done referring to it:
1191 ;; "Pillage, *then* burn.")
1192 (free-alien res)))))
1195 To execute the above example, it is necessary to compile the C
1196 routine, e.g.: @samp{cc -c test.c && ld -shared -o test.so test.o} (In
1197 order to enable incremental loading with some linkers, you may need to
1198 say @samp{cc -G 0 -c test.c})
1200 Once the C code has been compiled, you can start up Lisp and load it
1201 in: @samp{sbcl} Lisp should start up with its normal prompt.
1203 Within Lisp, compile the Lisp file. (This step can be done
1204 separately. You don't have to recompile every time.)
1205 @samp{(compile-file "test.lisp")}
1207 Within Lisp, load the foreign object file to define the necessary
1208 symbols: @samp{(load-shared-object "test.so")}. This must be done
1209 before loading any code that refers to these symbols.
1211 Now you can load the compiled Lisp (``fasl'') file into Lisp:
1212 @samp{(load "test.fasl")}
1213 And once the Lisp file is loaded, you can call the
1214 Lisp routine that sets up the parameters and calls the C
1216 @samp{(test-c-call::call-cfun)}
1218 The C routine should print the following information to standard output:
1222 s = another Lisp string
1224 r->s = a Lisp string
1237 After return from the C function,
1238 the Lisp wrapper function should print the following output:
1241 back from C function
1244 And upon return from the Lisp wrapper function,
1245 before the next prompt is printed, the
1246 Lisp read-eval-print loop should print the following return values: