0.9.11.4
[sbcl.git] / doc / manual / ffi.texinfo
1 @node  Foreign Function Interface
2 @comment  node-name,  next,  previous,  up
3 @chapter Foreign Function Interface
4
5 This chapter describes SBCL's interface to C programs and
6 libraries (and, since C interfaces are a sort of @emph{lingua
7 franca} of the Unix world, to other programs and libraries in
8 general.)
9
10 @quotation
11 Note: In the modern Lisp world, the usual term for this functionality
12 is Foreign Function Interface, or @acronym{FFI}, where despite the
13 mention of ``function'' in this term, @acronym{FFI} also
14 refers to direct manipulation of C data structures as well as
15 functions. The traditional CMUCL terminology is Alien Interface, and
16 while that older terminology is no longer used much in the system
17 documentation, it still reflected in names in the implementation,
18 notably in the name of the @code{SB-ALIEN} package.
19 @end quotation
20
21 @menu
22 * Introduction to the Foreign Function Interface::  
23 * Foreign Types::               
24 * Operations On Foreign Values::  
25 * Foreign Variables::           
26 * Foreign Data Structure Examples::  
27 * Loading Shared Object Files::  
28 * Foreign Function Calls::      
29 * Step-By-Step Example of the Foreign Function Interface::  
30 @end menu
31
32 @node  Introduction to the Foreign Function Interface
33 @comment  node-name,  next,  previous,  up
34 @section Introduction to the Foreign Function Interface
35 @c AKA "Introduction to Aliens" in the CMU CL manual
36
37 Because of Lisp's emphasis on dynamic memory allocation and garbage
38 collection, Lisp implementations use non-C-like memory representations
39 for objects.  This representation mismatch creates friction when a Lisp
40 program must share objects with programs which expect C data.  There
41 are three common approaches to establishing communication:
42
43 @itemize
44 @item
45 The burden can be placed on the foreign program (and programmer) by
46 requiring the knowledge and use of the representations used internally
47 by the Lisp implementation.  This can require a considerable amount of
48 ``glue'' code on the C side, and that code tends to be sensitively
49 dependent on the internal implementation details of the Lisp system.
50
51 @item
52 The Lisp system can automatically convert objects back and forth
53 between the Lisp and foreign representations.  This is convenient, but
54 translation becomes prohibitively slow when large or complex data
55 structures must be shared. This approach is supported by the SBCL
56 @acronym{FFI}, and used automatically by the when passing integers and
57 strings.
58
59 @item
60 The Lisp program can directly manipulate foreign objects through the
61 use of extensions to the Lisp language.
62
63 @end itemize
64
65 SBCL, like CMUCL before it, relies primarily on the automatic
66 conversion and direct manipulation approaches. The @code{SB-ALIEN}
67 package provices a facility wherein foreign values of simple scalar
68 types are automatically converted and complex types are directly
69 manipulated in their foreign representation.  Additionally the
70 lower-level System Area Pointers (or @acronym{SAP}s) can be used where
71 necessary to provide untyped access to foreign memory.
72
73 Any foreign objects that can't automatically be converted into Lisp
74 values are represented by objects of type @code{alien-value}.  Since
75 Lisp is a dynamically typed language, even foreign objects must have a
76 run-time type; this type information is provided by encapsulating the
77 raw pointer to the foreign data within an @code{alien-value} object.
78
79 The type language and operations on foreign types are
80 intentionally similar to those of the C language.
81
82 @node  Foreign Types
83 @comment  node-name,  next,  previous,  up
84 @section Foreign Types
85 @c AKA "Alien Types" in the CMU CL manual
86
87 Alien types have a description language based on nested list
88 structure. For example the C type
89
90 @example
91 struct foo @{
92     int a;
93     struct foo *b[100];
94 @};
95 @end example
96
97 has the corresponding SBCL @acronym{FFI} type
98
99 @lisp
100 (struct foo
101   (a int)
102   (b (array (* (struct foo)) 100)))
103 @end lisp
104
105
106 @menu
107 * Defining Foreign Types::      
108 * Foreign Types and Lisp Types::  
109 * Foreign Type Specifiers::     
110 @end menu
111
112 @node  Defining Foreign Types
113 @comment  node-name,  next,  previous,  up
114 @subsection Defining Foreign Types
115
116 Types may be either named or anonymous.  With structure and union
117 types, the name is part of the type specifier, allowing recursively
118 defined types such as:
119
120 @lisp
121 (struct foo (a (* (struct foo))))
122 @end lisp
123
124 An anonymous structure or union type is specified by using the name
125 @code{nil}.  The @code{with-alien} macro defines a local scope which
126 ``captures'' any named type definitions.  Other types are not
127 inherently named, but can be given named abbreviations using the
128 @code{define-alien-type} macro.
129
130 @node  Foreign Types and Lisp Types
131 @comment  node-name,  next,  previous,  up
132 @subsection Foreign Types and Lisp Types
133
134 The foreign types form a subsystem of the SBCL type system.  An
135 @code{alien} type specifier provides a way to use any foreign type as a
136 Lisp type specifier.  For example,
137
138 @lisp
139 (typep @var{foo} '(alien (* int)))
140 @end lisp
141
142 can be used to determine whether @var{foo} is a pointer to a foreign
143 @code{int}. @code{alien} type specifiers can be used in the same ways
144 as ordinary Lisp type specifiers (like @code{string}.) Alien type
145 declarations are subject to the same precise type checking as any
146 other declaration.  @xref{Precise Type Checking}.
147
148 Note that the type identifiers used in the foreign type system overlap
149 with native Lisp type specifiers in some cases.  For example, the type
150 specifier @code{(alien single-float)} is identical to
151 @code{single-float}, since foreign floats are automatically converted
152 to Lisp floats.  When @code{type-of} is called on an alien value that
153 is not automatically converted to a Lisp value, then it will return an
154 @code{alien} type specifier.
155
156 @node  Foreign Type Specifiers
157 @comment  node-name,  next,  previous,  up
158 @subsection Foreign Type Specifiers
159
160 Note: All foreign type names are exported from the @code{sb-alien}
161 package. Some foreign type names are also symbols in
162 the @code{common-lisp} package, in which case they are
163 reexported from the @code{sb-alien} package, so that
164 e.g. it is legal to refer to @code{sb-alien:single-float}.
165
166 These are the basic foreign type specifiers: 
167
168 @itemize
169 @item
170 The foreign type specifier @code{(* @var{foo})} describes a pointer to
171 an object of type @var{foo}.  A pointed-to type @var{foo} of @code{t}
172 indicates a pointer to anything, similar to @code{void *} in
173 ANSI C. A null alien pointer can be detected with the
174 @code{sb-alien:null-alien} function.
175
176 @item
177 The foreign type specifier @code{(array @var{foo} &rest
178 dimensions)} describes array of the specified @code{dimensions},
179 holding elements of type @var{foo}. Note that (unlike in C) @code{(*
180 @var{foo})} and @code{(array @var{foo})} are considered to be
181 different types when type checking is done. If equivalence of pointer
182 and array types is desired, it may be explicitly coerced using
183 @code{sb-alien:cast}.
184
185 Arrays are accessed using @code{sb-alien:deref}, passing the indices
186 as additional arguments.  Elements are stored in column-major order
187 (as in C), so the first dimension determines only the size of the
188 memory block, and not the layout of the higher dimensions.  An array
189 whose first dimension is variable may be specified by using @code{nil}
190 as the first dimension.  Fixed-size arrays can be allocated as array
191 elements, structure slots or @code{sb-alien:with-alien}
192 variables. Dynamic arrays can only be allocated using
193 @code{sb-alien:make-alien}.
194
195 @item
196 The foreign type specifier @code{(sb-alien:struct @var{name} &rest
197 @var{fields})} describes a structure type with the specified
198 @var{name} and @var{fields}. Fields are allocated at the same offsets
199 used by the implementation's C compiler, as guessed by the SBCL
200 internals. An optional @code{:alignment} keyword argument can be
201 specified for each field to explicitly control the alignment of a
202 field. If @var{name} is @code{nil} then the structure is anonymous.
203
204 If a named foreign @code{struct} specifier is passed to
205 @code{define-alien-type} or @code{with-alien}, then this defines,
206 respectively, a new global or local foreign structure type.  If no
207 @var{fields} are specified, then the fields are taken
208 from the current (local or global) alien structure type definition of
209 @var{name}.
210
211 @item
212 The foreign type specifier @code{(sb-alien:union @var{name} &rest
213 @var{fields})} is similar to @code{sb-alien:struct}, but describes a
214 union type.  All fields are allocated at the same offset, and the size
215 of the union is the size of the largest field.  The programmer must
216 determine which field is active from context.
217
218 @item
219 The foreign type specifier @code{(sb-alien:enum @var{name} &rest
220 @var{specs})} describes an enumeration type that maps between integer
221 values and symbols. If @var{name} is @code{nil}, then the type is
222 anonymous.  Each element of the @var{specs} list is either a Lisp
223 symbol, or a list @code{(@var{symbol} @var{value})}.  @var{value} is
224 an integer. If @var{value} is not supplied, then it defaults to one
225 greater than the value for the preceding spec (or to zero if it is the
226 first spec).
227
228 @item
229 The foreign type specifier @code{(sb-alien:signed &optional
230 @var{bits})} specifies a signed integer with the specified number of
231 @var{bits} precision. The upper limit on integer
232 precision is determined by the machine's word size. If
233 @var{bits} is not specified, the maximum size will be
234 used.
235
236 @item
237 The foreign type specifier @code{(integer &optional @var{bits})}
238 is equivalent to the corresponding type specifier using
239 @code{sb-alien:signed} instead of @code{integer}.
240
241 @item
242 The foreign type specifier @code{(sb-alien:unsigned &optional
243 @var{bits})} is like corresponding type specifier using
244 @code{sb-alien:signed} except that the variable is treated as an
245 unsigned integer.
246
247 @item
248 The foreign type specifier @code{(boolean &optional @var{bits})} is
249 similar to an enumeration type, but maps from Lisp @code{nil} and
250 @code{t} to C @code{0} and @code{1} respectively. @var{bits}
251 determines the amount of storage allocated to hold the truth value.
252
253 @item
254 The foreign type specifier @code{single-float} describes a
255 floating-point number in IEEE single-precision format.
256
257 @item
258 The foreign type specifier @code{double-float} describes a
259 floating-point number in IEEE double-precision format.
260
261 @item
262 The foreign type specifier @code{(function @var{result-type} &rest
263 @var{arg-types})} describes a foreign function that takes arguments of
264 the specified @var{arg-types} and returns a result of type
265 @var{result-type}.  Note that the only context where a foreign
266 @code{function} type is directly specified is in the argument to
267 @code{sb-alien:alien-funcall}.  In all other contexts, foreign
268 functions are represented by foreign function pointer types: @code{(*
269 (function @dots{}))}.
270
271 @item
272 The foreign type specifier @code{sb-alien:system-area-pointer}
273 describes a pointer which is represented in Lisp as a
274 @code{system-area-pointer} object.  SBCL exports this type from
275 @code{sb-alien} because CMUCL did, but tentatively (as of the first
276 draft of this section of the manual, SBCL 0.7.6) it is deprecated,
277 since it doesn't seem to be required by user code.
278
279 @item
280 The foreign type specifier @code{sb-alien:void} is used in function
281 types to declare that no useful value is returned.  Using
282 @code{alien-funcall} to call a @code{void} foreign function will
283 return zero values.
284
285 @item
286 The foreign type specifier @code{sb-alien:c-string} is similar to
287 @code{(* char)}, but is interpreted as a null-terminated string, and is
288 automatically converted into a Lisp string when accessed; or if the
289 pointer is C @code{NULL} or @code{0}, then accessing it gives Lisp
290 @code{nil}.  Lisp strings of type @code{base-string} are stored with a
291 trailing NUL termination, so no copying (either by the user or the
292 implementation) is necessary when passing them to foreign code; strings
293 of type @code{(simple-array character (*))} are copied by the
294 implementation as required.
295
296 Assigning a Lisp string to a @code{c-string} structure field or
297 variable stores the contents of the string to the memory already
298 pointed to by that variable.  When a foreign object of type @code{(*
299 char)} is assigned to a @code{c-string}, then the
300 @code{c-string} pointer is assigned to.  This allows
301 @code{c-string} pointers to be initialized.  For example:
302
303 @lisp
304 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
305
306 (define-alien-type nil (struct foo (str c-string)))
307
308 (defun make-foo (str)
309   (let ((my-foo (make-alien (struct foo))))
310     (setf (slot my-foo 'str) (make-alien char (length str))
311           (slot my-foo 'str) str)
312     my-foo))
313 @end lisp
314
315 Storing Lisp @code{NIL} in a @code{c-string} writes C @code{NULL} to
316 the variable.
317
318 @item
319 @code{sb-alien} also exports translations of these C type
320 specifiers as foreign type specifiers: @code{sb-alien:char},
321 @code{sb-alien:short}, @code{sb-alien:int},
322 @code{sb-alien:long}, @code{sb-alien:unsigned-char},
323 @code{sb-alien:unsigned-short},
324 @code{sb-alien:unsigned-int},
325 @code{sb-alien:unsigned-long}, @code{sb-alien:float}, and
326 @code{sb-alien:double}.
327
328 @end itemize
329
330 @node  Operations On Foreign Values
331 @comment  node-name,  next,  previous,  up
332 @section Operations On Foreign Values
333 @c AKA "Alien Operations" in the CMU CL manual
334
335 This section describes how to read foreign values as Lisp values, how
336 to coerce foreign values to different kinds of foreign values, and how
337 to dynamically allocate and free foreign variables.
338
339 @menu
340 * Accessing Foreign Values::    
341 * Coercing Foreign Values::     
342 * Foreign Dynamic Allocation::  
343 @end menu
344
345 @node  Accessing Foreign Values
346 @comment  node-name,  next,  previous,  up
347 @subsection Accessing Foreign Values
348
349 @defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
350 @findex deref
351
352 The @code{sb-alien:deref} function returns the value pointed to by a
353 foreign pointer, or the value of a foreign array element. When
354 dereferencing a pointer, an optional single index can be specified to
355 give the equivalent of C pointer arithmetic; this index is scaled by
356 the size of the type pointed to. When dereferencing an array, the
357 number of indices must be the same as the number of dimensions in the
358 array type. @code{deref} can be set with @code{setf} to assign a new
359 value.
360 @end defun
361
362 @defun sb-alien:slot @var{struct-or-union} @var{slot-name}
363 @findex slot
364
365 The @code{sb-alien:slot} function extracts the value of the slot named
366 @var{slot-name} from a foreign @code{struct} or @code{union}. If
367 @var{struct-or-union} is a pointer to a structure or union, then it is
368 automatically dereferenced.  @code{sb-alien:slot} can be set with
369 @code{setf} to assign a new value. Note that @var{slot-name} is
370 evaluated, and need not be a compile-time constant (but only constant
371 slot accesses are efficiently compiled).
372 @end defun
373
374
375 @subsubsection Untyped memory
376
377 As noted at the beginning of the chapter, the System Area Pointer
378 facilities allow untyped access to foreign memory.  @acronym{SAP}s can
379 be converted to and from the usual typed foreign values using
380 @code{sap-alien} and @code{alien-sap} (described elsewhere), and also
381 to and from integers - raw machine addresses.  They should thus be
382 used with caution; corrupting the Lisp heap or other memory with
383 @acronym{SAP}s is trivial.
384
385 @defun sb-sys:int-sap @var{machine-address}
386 @findex int-sap
387
388 Creates a @acronym{SAP} pointing at the virtual address
389 @var{machine-address}.
390 @end defun
391
392 @defun sb-sys:sap-ref-32 @var{sap} @var{offset}
393 @findex sap-ref-32
394
395 Access the value of the memory location at @var{offset} bytes from
396 @var{sap}.  This form may also be used with @code{setf} to alter the
397 memory at that location.
398 @end defun
399
400 @defun sb-sys:sap= @var{sap1} @var{sap2}
401 @findex sap=
402
403 Compare @var{sap1} and @var{sap2} for equality.
404 @end defun
405
406 Similarly named functions exist for accessing other sizes of word,
407 other comparisons, and other conversions.  The reader is invited to
408 use @code{apropos} and @code{describe} for more details
409
410 @lisp
411 (apropos "sap" :sb-sys)
412 @end lisp
413
414
415 @node  Coercing Foreign Values
416 @comment  node-name,  next,  previous,  up
417 @subsection Coercing Foreign Values
418
419 @defun sb-alien:addr @var{alien-expr}
420 @findex addr
421
422 The @code{sb-alien:addr} macro returns a pointer to the location
423 specified by @var{alien-expr}, which must be either a foreign
424 variable, a use of @code{sb-alien:deref}, a use of
425 @code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
426 @end defun
427
428 @defun sb-alien:cast @var{foreign-value} @var{new-type}
429 @findex cast
430
431 The @code{sb-alien:cast} macro converts @var{foreign-value} to a new
432 foreign value with the specified @var{new-type}. Both types, old and
433 new, must be foreign pointer, array or function types.  Note that the
434 resulting Lisp foreign variable object is not @code{eq} to the
435 argument, but it does refer to the same foreign data bits.
436 @end defun
437
438 @defun sb-alien:sap-alien @var{sap} @var{type}
439 @findex sap-alien
440
441 The @code{sb-alien:sap-alien} function converts @var{sap} (a system
442 area pointer) to a foreign value with the specified
443 @var{type}. @var{type} is not evaluated.  </para>
444
445 The @var{type} must be some foreign pointer, array, or record type.
446 @end defun
447
448 @defun sb-alien:alien-sap @var{foreign-value} @var{type}
449 @findex alien-sap
450
451 The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
452 points to @var{alien-value}'s data.
453
454 The @var{foreign-value} must be of some foreign pointer, array, or
455 record type.
456 @end defun
457
458
459 @node  Foreign Dynamic Allocation
460 @comment  node-name,  next,  previous,  up
461 @subsection Foreign Dynamic Allocation
462
463 Lisp code can call the C standard library functions @code{malloc} and
464 @code{free} to dynamically allocate and deallocate foreign
465 variables. The Lisp code shares the same allocator with foreign C
466 code, so it's OK for foreign code to call @code{free} on the result of
467 Lisp @code{sb-alien:make-alien}, or for Lisp code to call
468 @code{sb-alien:free-alien} on foreign objects allocated by C
469 code.
470
471 @defmac sb-alien:make-alien @var{type} @var{size}
472 @findex make-alien
473
474 The @code{sb-alien:make-alien} macro
475 returns a dynamically allocated foreign value of the specified
476 @var{type} (which is not evaluated.)  The allocated memory is not
477 initialized, and may contain arbitrary junk.  If supplied,
478 @var{size} is an expression to evaluate to compute the size of the
479 allocated object.  There are two major cases:
480
481 @itemize
482 @item
483 When @var{type} is a foreign array type, an array of that type is
484 allocated and a pointer to it is returned.  Note that you must use
485 @code{deref} to change the result to an array before you can use
486 @code{deref} to read or write elements:
487
488 @lisp
489 (cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
490 (defvar *foo* (make-alien (array char 10)))
491 (type-of *foo*) @result{} (alien (* (array (signed 8) 10)))
492 (setf (deref (deref foo) 0) 10) @result{} 10
493 @end lisp
494
495 If supplied, @var{size} is used as the first dimension for the
496     array.
497
498 @item
499 When @var{type} is any other foreign type, then an object for that
500 type is allocated, and a pointer to it is returned.  So
501 @code{(make-alien int)} returns a @code{(* int)}.  If @var{size} is
502 specified, then a block of that many objects is allocated, with the
503 result pointing to the first one.
504
505 @end itemize
506
507 @end defmac
508
509 @defun sb-alien:free-alien @var{foreign-value}
510 @findex free-alien
511
512 The @code{sb-alien:free-alien} function
513 frees the storage for @var{foreign-value}, 
514 which must have been allocated with Lisp @code{make-alien}
515 or C @code{malloc}.
516
517 See also the @code{sb-alien:with-alien} macro, which allocates foreign
518 values on the stack.
519 @end defun
520
521 @node  Foreign Variables
522 @comment  node-name,  next,  previous,  up
523 @section Foreign Variables
524 @c AKA "Alien Variables" in the CMU CL manual
525
526 Both local (stack allocated) and external (C global) foreign variables
527 are supported.
528
529 @menu
530 * Local Foreign Variables::     
531 * External Foreign Variables::  
532 @end menu
533
534 @node  Local Foreign Variables
535 @comment  node-name,  next,  previous,  up
536 @subsection Local Foreign Variables
537
538 @defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
539 @findex with-alien
540
541 The @code{with-alien} macro establishes local foreign variables with
542 the specified alien types and names.  This form is analogous to
543 defining a local variable in C: additional storage is allocated, and
544 the initial value is copied.  This form is less analogous to
545 @code{LET}-allocated Lisp variables, since the variables can't be
546 captured in closures: they live only for the dynamic extent of the
547 body, and referring to them outside is a gruesome error.
548
549 The @var{var-definitions} argument is a list of 
550 variable definitions, each of the form
551 @lisp
552 (@var{name} @var{type} &optional @var{initial-value})
553 @end lisp
554
555 The names of the variables are established as symbol-macros; the
556 bindings have lexical scope, and may be assigned with @code{setq} or
557 @code{setf}.
558  
559 The @code{with-alien} macro also establishes a new scope for named
560 structures and unions.  Any @var{type} specified for a variable may
561 contain named structure or union types with the slots specified.
562 Within the lexical scope of the binding specifiers and body, a locally
563 defined foreign structure type @var{foo} can be referenced by its name
564 using @code{(struct @var{foo})}.
565 @end defmac
566
567 @node  External Foreign Variables
568 @comment  node-name,  next,  previous,  up
569 @subsection External Foreign Variables
570
571 External foreign names are strings, and Lisp names are symbols. When
572 an external foreign value is represented using a Lisp variable, there
573 must be a way to convert from one name syntax into the other. The
574 macros @code{extern-alien}, @code{define-alien-variable} and
575 @code{define-alien-routine} use this conversion heuristic:
576
577 @itemize
578
579 @item
580 Alien names are converted to Lisp names by uppercasing and replacing
581 underscores with hyphens.
582
583 @item
584 Conversely, Lisp names are converted to alien names by lowercasing and
585 replacing hyphens with underscores.
586
587 @item
588 Both the Lisp symbol and alien string names may be separately
589 specified by using a list of the form
590
591 @lisp
592 (alien-string lisp-symbol)
593 @end lisp
594
595 @end itemize
596
597 @defmac sb-alien:define-alien-variable @var{name} @var{type}
598 @findex define-alien-variable
599
600 The @code{define-alien-variable} macro defines @var{name} as an
601 external foreign variable of the specified foreign @code{type}.
602 @var{name} and @code{type} are not evaluated.  The Lisp name of the
603 variable (see above) becomes a global alien variable.  Global alien
604 variables are effectively ``global symbol macros''; a reference to the
605 variable fetches the contents of the external variable.  Similarly,
606 setting the variable stores new contents -- the new contents must be
607 of the declared @code{type}. Someday, they may well be implemented
608 using the @acronym{ANSI} @code{define-symbol-macro} mechanism, but as
609 of SBCL 0.7.5, they are still implemented using an older more-or-less
610 parallel mechanism inherited from CMUCL.
611   
612 For example, to access a C-level counter @var{foo}, one could write
613
614 @lisp
615 (define-alien-variable "foo" int)
616 ;; Now it is possible to get the value of the C variable foo simply by
617 ;; referencing that Lisp variable:
618 (print foo)
619 (setf foo 14)
620 (incf foo)
621 @end lisp
622 @end defmac
623
624 @defun sb-alien:get-errno
625 @findex get-errno
626
627 Since in modern C libraries, the @code{errno} ``variable'' is typically
628 no longer a variable, but some bizarre artificial construct
629 which behaves superficially like a variable within a given thread,
630 it can no longer reliably be accessed through the ordinary 
631 @code{define-alien-variable} mechanism. Instead, SBCL provides
632 the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
633 @end defun
634
635 @defmac sb-alien:extern-alien @var{name} @var{type}
636 @findex extern-alien
637
638 The @code{extern-alien} macro returns an alien with the specified
639 @var{type} which points to an externally defined value.  @var{name} is
640 not evaluated, and may be either a string or a symbol.  @var{type} is
641 an unevaluated alien type specifier.
642 @end defmac
643
644 @node  Foreign Data Structure Examples
645 @comment  node-name,  next,  previous,  up
646 @section Foreign Data Structure Examples
647 @c AKA "Alien Data Structure Example" in the CMU CL manual
648
649 Now that we have alien types, operations and variables, we can
650 manipulate foreign data structures.  This C declaration
651
652 @example
653 struct foo @{
654     int a;
655     struct foo *b[100];
656 @};
657 @end example
658
659 can be translated into the following alien type:
660
661 @lisp
662 (define-alien-type nil
663   (struct foo
664     (a int)
665     (b (array (* (struct foo)) 100))))
666 @end lisp
667
668 Once the @code{foo} alien type has been defined as above, the C
669 expression
670
671 @example
672 struct foo f;
673 f.b[7].a;
674 @end example
675
676 can be translated in this way:
677
678 @lisp
679 (with-alien ((f (struct foo)))
680   (slot (deref (slot f 'b) 7) 'a)
681   ;;
682   ;; Do something with f...
683   )
684 @end lisp
685
686 Or consider this example of an external C variable and some accesses:
687
688 @example
689 struct c_struct @{
690         short x, y;
691         char a, b;
692         int z;
693         c_struct *n;
694 @};
695 extern struct c_struct *my_struct;
696 my_struct->x++;
697 my_struct->a = 5;
698 my_struct = my_struct->n;
699 @end example
700
701 which can be manipulated in Lisp like this:
702
703 @lisp
704 (define-alien-type nil
705   (struct c-struct
706           (x short)
707           (y short)
708           (a char)
709           (b char)
710           (z int)
711           (n (* c-struct))))
712 (define-alien-variable "my_struct" (* c-struct))
713 (incf (slot my-struct 'x))
714 (setf (slot my-struct 'a) 5)
715 (setq my-struct (slot my-struct 'n))
716 @end lisp
717
718 @node  Loading Shared Object Files
719 @comment  node-name,  next,  previous,  up
720 @section Loading Shared Object Files
721
722 Foreign object files can be loaded into the running Lisp process by
723 calling @code{load-shared-object}.
724
725 @include fun-sb-alien-load-shared-object.texinfo
726
727 @node  Foreign Function Calls
728 @comment  node-name,  next,  previous,  up
729 @section Foreign Function Calls
730
731 The foreign function call interface allows a Lisp program to call
732 many functions written in languages that use the C calling convention.
733
734 Lisp sets up various signal handling routines and other environment
735 information when it first starts up, and expects these to be in place
736 at all times. The C functions called by Lisp should not change the
737 environment, especially the signal handlers: the signal handlers
738 installed by Lisp typically have interesting flags set (e.g to request
739 machine context information, or for signal delivery on an alternate
740 stack) which the Lisp runtime relies on for correct operation.
741 Precise details of how this works may change without notice between
742 versions; the source, or the brain of a friendly SBCL developer, is
743 the only documentation.  Users of a Lisp built with the
744 @code{:sb-thread} feature should also read the section about threads,
745 @ref{Threading}.
746
747 @menu
748 * The alien-funcall Primitive::  
749 * The define-alien-routine Macro::  
750 * define-alien-routine Example::  
751 * Calling Lisp From C::         
752 @end menu
753
754 @node  The alien-funcall Primitive
755 @comment  node-name,  next,  previous,  up
756 @subsection The @code{alien-funcall} Primitive
757
758 @defun sb-alien:alien-funcall @var{alien-function} &rest @var{arguments}
759 @findex alien-funcall
760
761 The @code{alien-funcall} function is the foreign function call
762 primitive: @var{alien-function} is called with the supplied
763 @var{arguments} and its C return value is returned as a Lisp value.
764 The @var{alien-function} is an arbitrary run-time expression; to refer
765 to a constant function, use @code{extern-alien} or a value defined by
766 @code{define-alien-routine}.
767   
768 The type of @code{alien-function} must be @code{(alien (function
769 ...))}  or @code{(alien (* (function ...)))}.  The function type is
770 used to determine how to call the function (as though it was declared
771 with a prototype.)  The type need not be known at compile time, but
772 only known-type calls are efficiently compiled.  Limitations:
773
774 @itemize
775
776 @item
777 Structure type return values are not implemented.
778
779 @item
780 Passing of structures by value is not implemented.
781
782 @end itemize
783
784 @end defun
785
786 Here is an example which allocates a @code{(struct foo)}, calls a
787 foreign function to initialize it, then returns a Lisp vector of all
788 the @code{(* (struct foo))} objects filled in by the foreign call:
789
790 @lisp
791 ;; Allocate a foo on the stack.
792 (with-alien ((f (struct foo)))
793   ;; Call some C function to fill in foo fields.
794   (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
795                  (addr f))
796   ;; Find how many foos to use by getting the A field.
797   (let* ((num (slot f 'a))
798          (result (make-array num)))
799     ;; Get a pointer to the array so that we don't have to keep extracting it:
800     (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
801       ;; Loop over the first N elements and stash them in the result vector.
802       (dotimes (i num)
803         (setf (svref result i) (deref (deref a) i)))
804       ;; Voila.
805       result)))
806 @end lisp
807
808 @node  The define-alien-routine Macro
809 @comment  node-name,  next,  previous,  up
810 @subsection The @code{define-alien-routine} Macro
811
812 @defmac sb-alien:define-alien-routine @var{name} @var{result-type} &rest @var{arg-specifiers}
813 @findex define-alien-routine
814
815 The @code{define-alien-routine} macro is a convenience for
816 automatically generating Lisp interfaces to simple foreign functions.
817 The primary feature is the parameter style specification, which
818 translates the C pass-by-reference idiom into additional return
819 values.
820
821 @var{name} is usually a string external symbol, but may also be a
822 symbol Lisp name or a list of the foreign name and the Lisp name.  If
823 only one name is specified, the other is automatically derived as for
824 @code{extern-alien}.  @var{result-type} is the alien type of the
825 return value.
826
827 Each element of the @var{arg-specifiers} list 
828 specifies an argument to the foreign function, and is
829 of the form
830 @lisp
831 (aname atype &amp;optional style)
832 @end lisp
833
834 @var{aname} is the symbol name of the argument to the constructed
835 function (for documentation). @var{atype} is the alien type of
836 corresponding foreign argument.  The semantics of the actual call are
837 the same as for @code{alien-funcall}. @var{style} specifies how this
838 argument should be handled at call and return time, and should be one
839 of the following:
840
841 @itemize
842
843 @item
844 @code{:in} specifies that the argument is passed by value. This is the
845 default. @code{:in} arguments have no corresponding return value from
846 the Lisp function.
847
848 @item
849 @code{:copy} is similar to @code{:in}, but the argument is copied to a
850 pre-allocated object and a pointer to this object is passed to the
851 foreign routine.
852
853 @item
854 @code{:out} specifies a pass-by-reference output value.  The type of
855 the argument must be a pointer to a fixed-sized object (such as an
856 integer or pointer).  @code{:out} and @code{:in-out} style cannot be
857 used with pointers to arrays, records or functions.  An object of the
858 correct size is allocated on the stack, and its address is passed to
859 the foreign function.  When the function returns, the contents of this
860 location are returned as one of the values of the Lisp function (and
861 the location is automatically deallocated).
862
863 @item
864 @code{:in-out} is a combination of @code{:copy} and @code{:out}.  The
865 argument is copied to a pre-allocated object and a pointer to this
866 object is passed to the foreign routine.  On return, the contents of
867 this location is returned as an additional value.
868
869 @end itemize
870
871 @quotation
872 Note: Any efficiency-critical foreign interface function should be inline
873 expanded, which can be done by preceding the
874 @code{define-alien-routine} call with:
875
876 @lisp
877 (declaim (inline lisp-name))
878 @end lisp
879
880 In addition to avoiding the Lisp call overhead, this allows
881 pointers, word-integers and floats to be passed using non-descriptor
882 representations, avoiding consing.)
883 @end quotation
884
885 @end defmac
886
887 @node  define-alien-routine Example
888 @comment  node-name,  next,  previous,  up
889 @subsection @code{define-alien-routine} Example
890
891 Consider the C function @code{cfoo} with the following calling
892 convention:
893
894 @example
895 void
896 cfoo (str, a, i)
897     char *str;
898     char *a; /* update */
899     int *i; /* out */
900 @{
901   /* body of cfoo(...) */
902 @}
903 @end example
904
905 This can be described by the following call to
906 @code{define-alien-routine}:
907
908 @lisp
909 (define-alien-routine "cfoo" void
910   (str c-string)
911   (a char :in-out)
912   (i int :out))
913 @end lisp
914
915 The Lisp function @code{cfoo} will have two arguments (@var{str} and
916 @var{a}) and two return values (@var{a} and @var{i}).
917
918 @node  Calling Lisp From C
919 @comment  node-name,  next,  previous,  up
920 @subsection Calling Lisp From C
921
922 Calling Lisp functions from C is sometimes possible, but is extremely
923 hackish and poorly supported as of SBCL 0.7.5.  See @code{funcall0}
924 @dots{} @code{funcall3} in the runtime system. The arguments must be
925 valid SBCL object descriptors (so that e.g. fixnums must be
926 left-shifted by 2.) As of SBCL 0.7.5, the format of object descriptors
927 is documented only by the source code and, in parts, by the old CMUCL
928 @file{INTERNALS} documentation.
929
930 Note that the garbage collector moves objects, and won't be
931 able to fix up any references in C variables.  There are three
932 mechanisms for coping with this: 
933
934 @enumerate
935 @item
936 The @code{sb-ext:purify} moves all live Lisp
937 data into static or read-only areas such that it will never be moved
938 (or freed) again in the life of the Lisp session
939
940 @item
941 @code{sb-sys:with-pinned-objects} is a macro which arranges for some
942 set of objects to be pinned in memory for the dynamic extent of its
943 body forms.  On ports which use the generational garbage collector (as
944 of SBCL 0.8.3, only the x86) this has a page granularity - i.e. the
945 entire 4k page or pages containing the objects will be locked down. On
946 other ports it is implemented by turning off GC for the duration (so
947 could be said to have a whole-world granularity).
948
949 @item
950 Disable GC, using the @code{without-gcing} macro or @code{gc-off}
951 call.
952 @end enumerate
953
954 @c <!-- FIXME: This is a "changebar" section from the CMU CL manual.
955 @c      I (WHN 2002-07-14) am not very familiar with this content, so 
956 @c      I'm not immediately prepared to try to update it for SBCL, and
957 @c      I'm not feeling masochistic enough to work to encourage this
958 @c      kind of low-level hack anyway. However, I acknowledge that callbacks
959 @c      are sometimes really really necessary, so I include the original
960 @c      text in case someone is hard-core enough to benefit from it. If
961 @c      anyone brings the information up to date for SBCL, it belong
962 @c      either in the main manual or on a CLiki SBCL Internals page.
963 @c LaTeX \subsection{Accessing Lisp Arrays}
964 @c LaTeX 
965 @c LaTeX Due to the way \cmucl{} manages memory, the amount of memory that can
966 @c LaTeX be dynamically allocated by \code{malloc} or \funref{make-alien} is
967 @c LaTeX limited\footnote{\cmucl{} mmaps a large piece of memory for it's own
968 @c LaTeX   use and this memory is typically about 8 MB above the start of the C
969 @c LaTeX   heap.  Thus, only about 8 MB of memory can be dynamically
970 @c LaTeX   allocated.}.
971
972 @c Empirically determined to be considerably >8Mb on this x86 linux
973 @c machine, but I don't know what the actual values are - dan 2003.09.01
974
975 @c Note that this technique is used in SB-GROVEL in the SBCL contrib
976
977 @c LaTeX 
978 @c LaTeX To overcome this limitation, it is possible to access the content of
979 @c LaTeX Lisp arrays which are limited only by the amount of physical memory
980 @c LaTeX and swap space available.  However, this technique is only useful if
981 @c LaTeX the foreign function takes pointers to memory instead of allocating
982 @c LaTeX memory for itself.  In latter case, you will have to modify the
983 @c LaTeX foreign functions.
984 @c LaTeX 
985 @c LaTeX This technique takes advantage of the fact that \cmucl{} has
986 @c LaTeX specialized array types (\pxlref{specialized-array-types}) that match
987 @c LaTeX a typical C array.  For example, a \code{(simple-array double-float
988 @c LaTeX   (100))} is stored in memory in essentially the same way as the C
989 @c LaTeX array \code{double x[100]} would be.  The following function allows us
990 @c LaTeX to get the physical address of such a Lisp array:
991 @c LaTeX \begin{example}
992 @c LaTeX (defun array-data-address (array)
993 @c LaTeX   "Return the physical address of where the actual data of an array is
994 @c LaTeX stored.
995 @c LaTeX 
996 @c LaTeX ARRAY must be a specialized array type in CMU Lisp.  This means ARRAY
997 @c LaTeX must be an array of one of the following types:
998 @c LaTeX 
999 @c LaTeX                   double-float
1000 @c LaTeX                   single-float
1001 @c LaTeX                   (unsigned-byte 32)
1002 @c LaTeX                   (unsigned-byte 16)
1003 @c LaTeX                   (unsigned-byte  8)
1004 @c LaTeX                   (signed-byte 32)
1005 @c LaTeX                   (signed-byte 16)
1006 @c LaTeX                   (signed-byte  8)
1007 @c LaTeX "
1008 @c LaTeX   (declare (type (or #+signed-array (array (signed-byte 8))
1009 @c LaTeX                      #+signed-array (array (signed-byte 16))
1010 @c LaTeX                      #+signed-array (array (signed-byte 32))
1011 @c LaTeX                      (array (unsigned-byte 8))
1012 @c LaTeX                      (array (unsigned-byte 16))
1013 @c LaTeX                      (array (unsigned-byte 32))
1014 @c LaTeX                      (array single-float)
1015 @c LaTeX                      (array double-float))
1016 @c LaTeX                  array)
1017 @c LaTeX            (optimize (speed 3) (safety 0))
1018 @c LaTeX            (ext:optimize-interface (safety 3)))
1019 @c LaTeX   ;; with-array-data will get us to the actual data.  However, because
1020 @c LaTeX   ;; the array could have been displaced, we need to know where the
1021 @c LaTeX   ;; data starts.
1022 @c LaTeX   (lisp::with-array-data ((data array)
1023 @c LaTeX                           (start)
1024 @c LaTeX                           (end))
1025 @c LaTeX     (declare (ignore end))
1026 @c LaTeX     ;; DATA is a specialized simple-array.  Memory is laid out like this:
1027 @c LaTeX     ;;
1028 @c LaTeX     ;;   byte offset    Value
1029 @c LaTeX     ;;        0         type code (should be 70 for double-float vector)
1030 @c LaTeX     ;;        4         4 * number of elements in vector
1031 @c LaTeX     ;;        8         1st element of vector
1032 @c LaTeX     ;;      ...         ...
1033 @c LaTeX     ;;
1034 @c LaTeX     (let ((addr (+ 8 (logandc1 7 (kernel:get-lisp-obj-address data))))
1035 @c LaTeX           (type-size (let ((type (array-element-type data)))
1036 @c LaTeX                        (cond ((or (equal type '(signed-byte 8))
1037 @c LaTeX                                   (equal type '(unsigned-byte 8)))
1038 @c LaTeX                               1)
1039 @c LaTeX                              ((or (equal type '(signed-byte 16))
1040 @c LaTeX                                   (equal type '(unsigned-byte 16)))
1041 @c LaTeX                               2)
1042 @c LaTeX                              ((or (equal type '(signed-byte 32))
1043 @c LaTeX                                   (equal type '(unsigned-byte 32)))
1044 @c LaTeX                               4)
1045 @c LaTeX                              ((equal type 'single-float)
1046 @c LaTeX                               4)
1047 @c LaTeX                              ((equal type 'double-float)
1048 @c LaTeX                               8)
1049 @c LaTeX                              (t
1050 @c LaTeX                               (error "Unknown specialized array element type"))))))
1051 @c LaTeX       (declare (type (unsigned-byte 32) addr)
1052 @c LaTeX                (optimize (speed 3) (safety 0) (ext:inhibit-warnings 3)))
1053 @c LaTeX       (system:int-sap (the (unsigned-byte 32)
1054 @c LaTeX                         (+ addr (* type-size start)))))))
1055 @c LaTeX \end{example}
1056 @c LaTeX 
1057 @c LaTeX Assume we have the C function below that we wish to use:
1058 @c LaTeX \begin{example}
1059 @c LaTeX   double dotprod(double* x, double* y, int n)
1060 @c LaTeX   \{
1061 @c LaTeX     int k;
1062 @c LaTeX     double sum = 0;
1063 @c LaTeX 
1064 @c LaTeX     for (k = 0; k < n; ++k) \{
1065 @c LaTeX       sum += x[k] * y[k];
1066 @c LaTeX     \}
1067 @c LaTeX   \}
1068 @c LaTeX \end{example}
1069 @c LaTeX The following example generates two large arrays in Lisp, and calls the C
1070 @c LaTeX function to do the desired computation.  This would not have been
1071 @c LaTeX possible using \code{malloc} or \code{make-alien} since we need about
1072 @c LaTeX 16 MB of memory to hold the two arrays.
1073 @c LaTeX \begin{example}
1074 @c LaTeX   (define-alien-routine "dotprod" double
1075 @c LaTeX     (x (* double-float) :in)
1076 @c LaTeX     (y (* double-float) :in)
1077 @c LaTeX     (n int :in))
1078 @c LaTeX     
1079 @c LaTeX   (let ((x (make-array 1000000 :element-type 'double-float))
1080 @c LaTeX         (y (make-array 1000000 :element-type 'double-float)))
1081 @c LaTeX     ;; Initialize X and Y somehow
1082 @c LaTeX     (let ((x-addr (system:int-sap (array-data-address x)))
1083 @c LaTeX           (y-addr (system:int-sap (array-data-address y))))
1084 @c LaTeX       (dotprod x-addr y-addr 1000000)))    
1085 @c LaTeX \end{example}
1086 @c LaTeX In this example, it may be useful to wrap the inner \code{let}
1087 @c LaTeX expression in an \code{unwind-protect} that first turns off garbage
1088 @c LaTeX collection and then turns garbage collection on afterwards.  This will
1089 @c LaTeX prevent garbage collection from moving \code{x} and \code{y} after we
1090 @c LaTeX have obtained the (now erroneous) addresses but before the call to
1091 @c LaTeX \code{dotprod} is made.
1092 @c LaTeX 
1093 @c -->
1094
1095
1096 @node  Step-By-Step Example of the Foreign Function Interface
1097 @comment  node-name,  next,  previous,  up
1098 @section Step-By-Step Example of the Foreign Function Interface
1099
1100 This section presents a complete example of an interface to a somewhat
1101 complicated C function.
1102
1103 Suppose you have the following C function which you want to be able to
1104 call from Lisp in the file @file{test.c}
1105
1106 @example
1107 struct c_struct
1108 @{
1109   int x;
1110   char *s;
1111 @};
1112  
1113 struct c_struct *c_function (i, s, r, a)
1114     int i;
1115     char *s;
1116     struct c_struct *r;
1117     int a[10];
1118 @{
1119   int j;
1120   struct c_struct *r2;
1121  
1122   printf("i = %d\n", i);
1123   printf("s = %s\n", s);
1124   printf("r->x = %d\n", r->x);
1125   printf("r->s = %s\n", r->s);
1126   for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
1127   r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
1128   r2->x = i + 5;
1129   r2->s = "a C string";
1130   return(r2);
1131 @};
1132 @end example
1133
1134 It is possible to call this C function from Lisp using the file
1135 @file{test.lisp} containing
1136
1137 @lisp
1138 (cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
1139 (cl:in-package "TEST-C-CALL")
1140
1141 ;;; Define the record C-STRUCT in Lisp.
1142 (define-alien-type nil
1143     (struct c-struct
1144             (x int)
1145             (s c-string)))
1146
1147 ;;; Define the Lisp function interface to the C routine.  It returns a
1148 ;;; pointer to a record of type C-STRUCT.  It accepts four parameters:
1149 ;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
1150 ;;; record; and A, a pointer to the array of 10 ints.
1151 ;;;
1152 ;;; The INLINE declaration eliminates some efficiency notes about heap
1153 ;;; allocation of alien values.
1154 (declaim (inline c-function))
1155 (define-alien-routine c-function
1156     (* (struct c-struct))
1157   (i int)
1158   (s c-string)
1159   (r (* (struct c-struct)))
1160   (a (array int 10)))
1161
1162 ;;; a function which sets up the parameters to the C function and
1163 ;;; actually calls it
1164 (defun call-cfun ()
1165   (with-alien ((ar (array int 10))
1166                (c-struct (struct c-struct)))
1167     (dotimes (i 10)                     ; Fill array.
1168       (setf (deref ar i) i))
1169     (setf (slot c-struct 'x) 20)
1170     (setf (slot c-struct 's) "a Lisp string")
1171
1172     (with-alien ((res (* (struct c-struct))
1173                       (c-function 5 "another Lisp string" (addr c-struct) ar)))
1174       (format t "~&amp;back from C function~%")
1175       (multiple-value-prog1
1176           (values (slot res 'x)
1177                   (slot res 's))
1178
1179         ;; Deallocate result. (after we are done referring to it:
1180         ;; "Pillage, *then* burn.")
1181         (free-alien res)))))
1182 @end lisp
1183
1184 To execute the above example, it is necessary to compile the C
1185 routine, e.g.: @samp{cc -c test.c && ld -shared -o test.so test.o} (In
1186 order to enable incremental loading with some linkers, you may need to
1187 say @samp{cc -G 0 -c test.c})
1188
1189 Once the C code has been compiled, you can start up Lisp and load it in:
1190 @samp{sbcl}.  Lisp should start up with its normal prompt.
1191
1192 Within Lisp, compile the Lisp file. (This step can be done
1193 separately. You don't have to recompile every time.)
1194 @samp{(compile-file "test.lisp")}
1195
1196 Within Lisp, load the foreign object file to define the necessary
1197 symbols: @samp{(load-shared-object "test.so")}. 
1198
1199 Now you can load the compiled Lisp (``fasl'') file into Lisp:
1200 @samp{(load "test.fasl")}
1201 And once the Lisp file is loaded, you can call the 
1202 Lisp routine that sets up the parameters and calls the C
1203 function:
1204 @samp{(test-c-call::call-cfun)}
1205
1206 The C routine should print the following information to standard output:
1207
1208 @example
1209 i = 5
1210 s = another Lisp string
1211 r->x = 20
1212 r->s = a Lisp string
1213 a[0] = 0.
1214 a[1] = 1.
1215 a[2] = 2.
1216 a[3] = 3.
1217 a[4] = 4.
1218 a[5] = 5.
1219 a[6] = 6.
1220 a[7] = 7.
1221 a[8] = 8.
1222 a[9] = 9.
1223 @end example
1224
1225 After return from the C function,
1226 the Lisp wrapper function should print the following output:
1227
1228 @example
1229 back from C function
1230 @end example
1231
1232 And upon return from the Lisp wrapper function,
1233 before the next prompt is printed, the
1234 Lisp read-eval-print loop should print the following return values:
1235
1236 @example
1237 10
1238 "a C string"
1239 @end example