-@node The Foreign Function Interface
+@node Foreign Function Interface
@comment node-name, next, previous, up
-@chapter The Foreign Function Interface
+@chapter Foreign Function Interface
This chapter describes SBCL's interface to C programs and
-libraries (and, since C interfaces are a sort of @emph{ingua
+libraries (and, since C interfaces are a sort of @emph{lingua
franca} of the Unix world, to other programs and libraries in
general.)
* Operations On Foreign Values::
* Foreign Variables::
* Foreign Data Structure Examples::
-* Loading Unix Object Files::
+* Loading Shared Object Files::
* Foreign Function Calls::
* Step-By-Step Example of the Foreign Function Interface::
@end menu
dependent on the internal implementation details of the Lisp system.
@item
-The Lisp system can automatically convert objects back and forth
-between the Lisp and foreign representations. This is convenient, but
+The Lisp system can automatically convert objects back and forth between
+the Lisp and foreign representations. This is convenient, but
translation becomes prohibitively slow when large or complex data
structures must be shared. This approach is supported by the SBCL
-@acronym{FFI}, and used automatically by the when passing integers and
-strings.
+@acronym{FFI}, and used automatically when passing integers and strings.
@item
The Lisp program can directly manipulate foreign objects through the
SBCL, like CMUCL before it, relies primarily on the automatic
conversion and direct manipulation approaches. The @code{SB-ALIEN}
-package provices a facility wherein foreign values of simple scalar
+package provides a facility wherein foreign values of simple scalar
types are automatically converted and complex types are directly
manipulated in their foreign representation. Additionally the
lower-level System Area Pointers (or @acronym{SAP}s) can be used where
@code{sb-alien:null-alien} function.
@item
-The foreign type specifier @code{(array @var{foo} &optional
+The foreign type specifier @code{(array @var{foo} &rest
dimensions)} describes array of the specified @code{dimensions},
holding elements of type @var{foo}. Note that (unlike in C) @code{(*
@var{foo})} and @code{(array @var{foo})} are considered to be
The foreign type specifier @code{(sb-alien:struct @var{name} &rest
@var{fields})} describes a structure type with the specified
@var{name} and @var{fields}. Fields are allocated at the same offsets
-used by the implementation's C compiler. If @var{name} is @code{nil}
-then the structure is anonymous.
+used by the implementation's C compiler, as guessed by the SBCL
+internals. An optional @code{:alignment} keyword argument can be
+specified for each field to explicitly control the alignment of a
+field. If @var{name} is @code{nil} then the structure is anonymous.
If a named foreign @code{struct} specifier is passed to
@code{define-alien-type} or @code{with-alien}, then this defines,
@item
The foreign type specifier @code{(sb-alien:enum @var{name} &rest
@var{specs})} describes an enumeration type that maps between integer
-values and keywords. If @var{name} is @code{nil}, then the type is
+values and symbols. If @var{name} is @code{nil}, then the type is
anonymous. Each element of the @var{specs} list is either a Lisp
-keyword, or a list @code{(@var{keyword} @var{value})}. @var{value} is
+symbol, or a list @code{(@var{symbol} @var{value})}. @var{value} is
an integer. If @var{value} is not supplied, then it defaults to one
greater than the value for the preceding spec (or to zero if it is the
first spec).
return zero values.
@item
-The foreign type specifier @code{sb-alien:c-string} is similar to
+@cindex External formats
+The foreign type specifier @code{(sb-alien:c-string &key
+external-format element-type not-null)} is similar to
@code{(* char)}, but is interpreted as a null-terminated string, and
is automatically converted into a Lisp string when accessed; or if the
pointer is C @code{NULL} or @code{0}, then accessing it gives Lisp
-@code{nil}. Lisp strings are stored with a trailing NUL
-termination, so no copying (either by the user or the implementation)
-is necessary when passing them to foreign code.
+@code{nil} unless @code{not-null} is true, in which case a type-error
+is signalled.
+
+External format conversion is automatically done when Lisp strings are
+passed to foreign code, or when foreign strings are passed to Lisp code.
+If the type specifier has an explicit @code{external-format}, that
+external format will be used. Otherwise a default external format that
+has been determined at SBCL startup time based on the current locale
+settings will be used. For example, when the following alien routine is
+called, the Lisp string given as argument is converted to an
+@code{ebcdic} octet representation.
+
+@lisp
+(define-alien-routine test int (str (c-string :external-format :ebcdic-us)))
+@end lisp
+
+Lisp strings of type @code{base-string} are stored with a trailing NUL
+termination, so no copying (either by the user or the implementation) is
+necessary when passing them to foreign code, assuming that the
+@code{external-format} and @code{element-type} of the @code{c-string}
+type are compatible with the internal representation of the string. For
+an SBCL built with Unicode support that means an @code{external-format}
+of @code{:ascii} and an @code{element-type} of @code{base-char}. Without
+Unicode support the @code{external-format} can also be
+@code{:iso-8859-1}, and the @code{element-type} can also be
+@code{character}. If the @code{external-format} or @code{element-type}
+is not compatible, or the string is a @code{(simple-array character
+(*))}, this data is copied by the implementation as required.
Assigning a Lisp string to a @code{c-string} structure field or
variable stores the contents of the string to the memory already
@item
@code{sb-alien} also exports translations of these C type
-specifiers as foreign type specifiers: @code{sb-alien:char},
-@code{sb-alien:short}, @code{sb-alien:int},
-@code{sb-alien:long}, @code{sb-alien:unsigned-char},
-@code{sb-alien:unsigned-short},
-@code{sb-alien:unsigned-int},
-@code{sb-alien:unsigned-long}, @code{sb-alien:float}, and
-@code{sb-alien:double}.
+specifiers as foreign type specifiers:
+@code{char},
+@code{short},
+@code{int},
+@code{long},
+@code{unsigned-char},
+@code{unsigned-short},
+@code{unsigned-int},
+@code{unsigned-long},
+@code{float}, @code{double},
+@code{size-t}, and @code{off-t}.
@end itemize
@comment node-name, next, previous, up
@subsection Accessing Foreign Values
-@defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
-@findex deref
+@defun @sbalien{deref} @var{pointer-or-array} &rest @var{indices}
The @code{sb-alien:deref} function returns the value pointed to by a
foreign pointer, or the value of a foreign array element. When
value.
@end defun
-@defun sb-alien:slot @var{struct-or-union} &rest @var{slot-names}
-@findex slot
+@defun @sbalien{slot} @var{struct-or-union} @var{slot-name}
The @code{sb-alien:slot} function extracts the value of the slot named
@var{slot-name} from a foreign @code{struct} or @code{union}. If
used with caution; corrupting the Lisp heap or other memory with
@acronym{SAP}s is trivial.
-@defun sb-sys:int-sap @var{machine-address}
-@findex int-sap
+@defun @sbsys{int-sap} @var{machine-address}
Creates a @acronym{SAP} pointing at the virtual address
@var{machine-address}.
@end defun
-@defun sb-sys:sap-ref-32 @var{sap} @var{offset}
-@findex sap-ref-32
+@defun @sbsys{sap-ref-32} @var{sap} @var{offset}
Access the value of the memory location at @var{offset} bytes from
@var{sap}. This form may also be used with @code{setf} to alter the
memory at that location.
@end defun
-@defun sb-sys:sap= @var{sap1} @var{sap2}
-@findex sap=
+@defun @sbsys{sap=} @var{sap1} @var{sap2}
Compare @var{sap1} and @var{sap2} for equality.
@end defun
@comment node-name, next, previous, up
@subsection Coercing Foreign Values
-@defun sb-alien:addr @var{alien-expr}
-@findex addr
+@defmac @sbalien{addr} @var{alien-expr}
The @code{sb-alien:addr} macro returns a pointer to the location
specified by @var{alien-expr}, which must be either a foreign
variable, a use of @code{sb-alien:deref}, a use of
@code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
-@end defun
+@end defmac
-@defun sb-alien:cast @var{foreign-value} @var{new-type}
-@findex cast
+@defmac @sbalien{cast} @var{foreign-value} @var{new-type}
The @code{sb-alien:cast} macro converts @var{foreign-value} to a new
foreign value with the specified @var{new-type}. Both types, old and
new, must be foreign pointer, array or function types. Note that the
resulting Lisp foreign variable object is not @code{eq} to the
argument, but it does refer to the same foreign data bits.
-@end defun
+@end defmac
-@defun sb-alien:sap-alien @var{sap} @var{type}
-@findex sap-alien
+@defmac @sbalien{sap-alien} @var{sap} @var{type}
-The @code{sb-alien:sap-alien} function converts @var{sap} (a system
+The @code{sb-alien:sap-alien} macro converts @var{sap} (a system
area pointer) to a foreign value with the specified
-@var{type}. @var{type} is not evaluated. </para>
+@var{type}. @var{type} is not evaluated.
The @var{type} must be some foreign pointer, array, or record type.
-@end defun
+@end defmac
-@defun sb-alien:alien-sap @var{foreign-value} @var{type}
-@findex alien-sap
+@defun @sbalien{alien-sap} @var{foreign-value}
The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
points to @var{alien-value}'s data.
@subsection Foreign Dynamic Allocation
Lisp code can call the C standard library functions @code{malloc} and
-@code{free} to dynamically allocate and deallocate foreign
-variables. The Lisp code shares the same allocator with foreign C
-code, so it's OK for foreign code to call @code{free} on the result of
-Lisp @code{sb-alien:make-alien}, or for Lisp code to call
-@code{sb-alien:free-alien} on foreign objects allocated by C
-code.
-
-@defmac sb-alien:make-alien @var{type} @var{size}
-@findex make-alien
-
-The @code{sb-alien:make-alien} macro
-returns a dynamically allocated foreign value of the specified
-@var{type} (which is not evaluated.) The allocated memory is not
-initialized, and may contain arbitrary junk. If supplied,
-@var{size} is an expression to evaluate to compute the size of the
-allocated object. There are two major cases:
-
-@itemize
-@item
-When @var{type} is a foreign array type, an array of that type is
-allocated and a pointer to it is returned. Note that you must use
-@code{deref} to change the result to an array before you can use
-@code{deref} to read or write elements:
-
-@lisp
-(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
-(defvar *foo* (make-alien (array char 10)))
-(type-of *foo*) @result{} (alien (* (array (signed 8) 10)))
-(setf (deref (deref foo) 0) 10) @result{} 10
-@end lisp
-
-If supplied, @var{size} is used as the first dimension for the
- array.
-
-@item
-When @var{type} is any other foreign type, then an object for that
-type is allocated, and a pointer to it is returned. So
-@code{(make-alien int)} returns a @code{(* int)}. If @var{size} is
-specified, then a block of that many objects is allocated, with the
-result pointing to the first one.
-
-@end itemize
+@code{free} to dynamically allocate and deallocate foreign variables.
+The Lisp code shares the same allocator with foreign C code, so it's
+OK for foreign code to call @code{free} on the result of Lisp
+@code{sb-alien:make-alien}, or for Lisp code to call
+@code{sb-alien:free-alien} on foreign objects allocated by C code.
-@end defmac
-
-@defun sb-alien:free-alien @var{foreign-value}
-@findex free-alien
-
-The @code{sb-alien:free-alien} function
-frees the storage for @var{foreign-value},
-which must have been allocated with Lisp @code{make-alien}
-or C @code{malloc}.
-
-See also the @code{sb-alien:with-alien} macro, which allocates foreign
-values on the stack.
-@end defun
+@include macro-sb-alien-make-alien.texinfo
+@include fun-sb-alien-make-alien-string.texinfo
+@include fun-sb-alien-free-alien.texinfo
@node Foreign Variables
@comment node-name, next, previous, up
@comment node-name, next, previous, up
@subsection Local Foreign Variables
-@defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
-@findex with-alien
+@defmac @sbalien{with-alien} @var{var-definitions} &body @var{body}
The @code{with-alien} macro establishes local foreign variables with
the specified alien types and names. This form is analogous to
@end itemize
-@defmac sb-alien:define-alien-variable @var{name} @var{type}
-@findex define-alien-variable
+@defmac @sbalien{define-alien-variable} @var{name} @var{type}
The @code{define-alien-variable} macro defines @var{name} as an
external foreign variable of the specified foreign @code{type}.
@end lisp
@end defmac
-@defun sb-alien:get-errno
-@findex get-errno
+@defun @sbalien{get-errno}
Since in modern C libraries, the @code{errno} ``variable'' is typically
no longer a variable, but some bizarre artificial construct
the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
@end defun
-@defmac sb-alien:extern-alien @var{name} @var{type}
-@findex extern-alien
+@defmac @sbalien{extern-alien} @var{name} @var{type}
The @code{extern-alien} macro returns an alien with the specified
@var{type} which points to an externally defined value. @var{name} is
(setq my-struct (slot my-struct 'n))
@end lisp
-@node Loading Unix Object Files
+@node Loading Shared Object Files
@comment node-name, next, previous, up
-@section Loading Unix Object Files
+@section Loading Shared Object Files
Foreign object files can be loaded into the running Lisp process by
calling @code{load-shared-object}.
-The @code{sb-alien:load-shared-object} loads a single object file into
-the currently running Lisp. The external symbols defining routines and
-variables are made available for future external references (e.g. by
-@code{extern-alien}). Forward references to foreign symbols aren't
-supported: @code{load-shared-object} must be run before any of the
-defined symbols are referenced.
-
-@quotation
-Note: As of SBCL 0.7.5, all foreign code (code loaded with
-@code{load-1-function} or @code{load-function}) is lost when a Lisp
-core is saved with @code{sb-ext:save-lisp-and-die}, and no attempt is
-made to restore it when the core is loaded. Historically this has been
-an annoyance both for SBCL users and for CMUCL users. It's hard to
-solve this problem completely cleanly, but some generally-reliable
-partial solution might be useful. Once someone in either camp gets
-sufficiently annoyed to create it, SBCL is likely to adopt some
-mechanism for automatically restoring foreign code when a saved core
-is loaded.
-@end quotation
+@include fun-sb-alien-load-shared-object.texinfo
+@include fun-sb-alien-unload-shared-object.texinfo
@node Foreign Function Calls
@comment node-name, next, previous, up
@comment node-name, next, previous, up
@subsection The @code{alien-funcall} Primitive
-@defun sb-alien:alien-funcall @var{alien-function} &rest @var{arguments}
-@findex alien-funcall
+@defun @sbalien{alien-funcall} @var{alien-function} &rest @var{arguments}
The @code{alien-funcall} function is the foreign function call
primitive: @var{alien-function} is called with the supplied
@comment node-name, next, previous, up
@subsection The @code{define-alien-routine} Macro
-@defmac sb-alien:define-alien-routine @var{name} @var{result-type} &rest @var{arg-specifiers}
-@findex define-alien-routine
+@defmac @sbalien{define-alien-routine} @var{name} @var{result-type} &rest @var{arg-specifiers}
The @code{define-alien-routine} macro is a convenience for
automatically generating Lisp interfaces to simple foreign functions.
could be said to have a whole-world granularity).
@item
-Disable GC, using the @code{without-gcing} macro or @code{gc-off}
-call.
+Disable GC, using the @code{without-gcing} macro.
@end enumerate
@c <!-- FIXME: This is a "changebar" section from the CMU CL manual.
printf("s = %s\n", s);
printf("r->x = %d\n", r->x);
printf("r->s = %s\n", r->s);
- for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
+ for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
r2->x = i + 5;
r2->s = "a C string";
order to enable incremental loading with some linkers, you may need to
say @samp{cc -G 0 -c test.c})
-Once the C code has been compiled, you can start up Lisp and load it
-in: @samp{sbcl} Lisp should start up with its normal prompt.
+Once the C code has been compiled, you can start up Lisp and load it in:
+@samp{sbcl}. Lisp should start up with its normal prompt.
Within Lisp, compile the Lisp file. (This step can be done
separately. You don't have to recompile every time.)
@samp{(compile-file "test.lisp")}
Within Lisp, load the foreign object file to define the necessary
-symbols: @samp{(load-shared-object "test.so")}. This must be done
-before loading any code that refers to these symbols.
+symbols: @samp{(load-shared-object "test.so")}.
Now you can load the compiled Lisp (``fasl'') file into Lisp:
@samp{(load "test.fasl")}
projects / sbcl.git / blobdiff