-@node The Foreign Function Interface, Function Index, Beyond The ANSI Standard, Top
+@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
-@node Introduction to the Foreign Function Interface, Foreign Types, The Foreign Function Interface, The Foreign Function Interface
+@node Introduction to the Foreign Function Interface
@comment node-name, next, previous, up
@section Introduction to the Foreign Function Interface
@c AKA "Introduction to Aliens" in the CMU CL manual
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
The type language and operations on foreign types are
intentionally similar to those of the C language.
-@node Foreign Types, Operations On Foreign Values, Introduction to the Foreign Function Interface, The Foreign Function Interface
+@node Foreign Types
@comment node-name, next, previous, up
@section Foreign Types
@c AKA "Alien Types" in the CMU CL manual
* Foreign Type Specifiers::
@end menu
-@node Defining Foreign Types, Foreign Types and Lisp Types, Foreign Types, Foreign Types
+@node Defining Foreign Types
@comment node-name, next, previous, up
@subsection Defining Foreign Types
inherently named, but can be given named abbreviations using the
@code{define-alien-type} macro.
-@node Foreign Types and Lisp Types, Foreign Type Specifiers, Defining Foreign Types, Foreign Types
+@node Foreign Types and Lisp Types
@comment node-name, next, previous, up
@subsection Foreign Types and Lisp Types
is not automatically converted to a Lisp value, then it will return an
@code{alien} type specifier.
-@node Foreign Type Specifiers, , Foreign Types and Lisp Types, Foreign Types
+@node Foreign Type Specifiers
@comment node-name, next, previous, up
@subsection Foreign Type Specifiers
@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
-@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.
+The foreign type specifier @code{(sb-alien:c-string &key external-format
+element-type)} 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}.
+
+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
@end itemize
-@node Operations On Foreign Values, Foreign Variables, Foreign Types, The Foreign Function Interface
+@node Operations On Foreign Values
@comment node-name, next, previous, up
@section Operations On Foreign Values
@c AKA "Alien Operations" in the CMU CL manual
* Foreign Dynamic Allocation::
@end menu
-@node Accessing Foreign Values, Coercing Foreign Values, Operations On Foreign Values, Operations On Foreign Values
+@node Accessing Foreign Values
@comment node-name, next, previous, up
@subsection Accessing Foreign Values
@defun sb-alien:deref @var{pointer-or-array} &rest @var{indices}
+@findex deref
The @code{sb-alien:deref} function returns the value pointed to by a
foreign pointer, or the value of a foreign array element. When
number of indices must be the same as the number of dimensions in the
array type. @code{deref} can be set with @code{setf} to assign a new
value.
-
@end defun
-@defun sb-alien:slot @var{struct-or-union} &rest @var{slot-names}
-
+@defun sb-alien:slot @var{struct-or-union} @var{slot-name}
+@findex slot
+
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
@var{struct-or-union} is a pointer to a structure or union, then it is
@acronym{SAP}s is trivial.
@defun sb-sys:int-sap @var{machine-address}
+@findex int-sap
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
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
@end defun
@defun sb-sys:sap= @var{sap1} @var{sap2}
+@findex sap=
Compare @var{sap1} and @var{sap2} for equality.
@end defun
@end lisp
-@node Coercing Foreign Values, Foreign Dynamic Allocation, Accessing Foreign Values, Operations On Foreign Values
+@node Coercing Foreign Values
@comment node-name, next, previous, up
@subsection Coercing Foreign Values
@defun sb-alien:addr @var{alien-expr}
-
+@findex addr
+
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
@end defun
@defun sb-alien:cast @var{foreign-value} @var{new-type}
-
+@findex cast
+
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
@end defun
@defun sb-alien:sap-alien @var{sap} @var{type}
-
+@findex sap-alien
+
The @code{sb-alien:sap-alien} function 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
@defun sb-alien:alien-sap @var{foreign-value} @var{type}
+@findex alien-sap
The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
points to @var{alien-value}'s data.
@end defun
-@node Foreign Dynamic Allocation, , Coercing Foreign Values, Operations On Foreign Values
+@node Foreign Dynamic Allocation
@comment node-name, next, previous, up
@subsection Foreign Dynamic Allocation
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
@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},
values on the stack.
@end defun
-@node Foreign Variables, Foreign Data Structure Examples, Operations On Foreign Values, The Foreign Function Interface
+@node Foreign Variables
@comment node-name, next, previous, up
@section Foreign Variables
@c AKA "Alien Variables" in the CMU CL manual
* External Foreign Variables::
@end menu
-@node Local Foreign Variables, External Foreign Variables, Foreign Variables, Foreign Variables
+@node Local Foreign Variables
@comment node-name, next, previous, up
@subsection Local Foreign Variables
@defmac sb-alien:with-alien @var{var-definitions} &body @var{body}
+@findex with-alien
The @code{with-alien} macro establishes local foreign variables with
the specified alien types and names. This form is analogous to
using @code{(struct @var{foo})}.
@end defmac
-@node External Foreign Variables, , Local Foreign Variables, Foreign Variables
+@node External Foreign Variables
@comment node-name, next, previous, up
@subsection External Foreign Variables
@end itemize
@defmac sb-alien:define-alien-variable @var{name} @var{type}
+@findex define-alien-variable
The @code{define-alien-variable} macro defines @var{name} as an
external foreign variable of the specified foreign @code{type}.
@end defmac
@defun sb-alien:get-errno
+@findex get-errno
Since in modern C libraries, the @code{errno} ``variable'' is typically
no longer a variable, but some bizarre artificial construct
@end defun
@defmac sb-alien:extern-alien @var{name} @var{type}
+@findex extern-alien
The @code{extern-alien} macro returns an alien with the specified
@var{type} which points to an externally defined value. @var{name} is
an unevaluated alien type specifier.
@end defmac
-@node Foreign Data Structure Examples, Loading Unix Object Files, Foreign Variables, The Foreign Function Interface
+@node Foreign Data Structure Examples
@comment node-name, next, previous, up
@section Foreign Data Structure Examples
@c AKA "Alien Data Structure Example" in the CMU CL manual
(setq my-struct (slot my-struct 'n))
@end lisp
-@node Loading Unix Object Files, Foreign Function Calls, Foreign Data Structure Examples, The Foreign Function Interface
+@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 the functions @code{load-foreign} or @code{load-1-foreign}.
-
-The @code{sb-alien:load-1-foreign} function is the more primitive of
-the two operations. It 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-1-foreign} must be run before any of the defined
-symbols are referenced.
-
-@code{sb-alien:load-foreign} is built in terms of
-@code{load-1-foreign} and some other machinery like
-@code{sb-ext:run-program}. It accepts a list of files and libraries,
-and runs the linker on the files and libraries, creating an absolute
-Unix object file which is then processed by @code{load-1-foreign}.
-
-@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
+calling @code{load-shared-object}.
+@include fun-sb-alien-load-shared-object.texinfo
-@node Foreign Function Calls, Step-By-Step Example of the Foreign Function Interface, Loading Unix Object Files, The Foreign Function Interface
+@node Foreign Function Calls
@comment node-name, next, previous, up
@section Foreign Function Calls
* Calling Lisp From C::
@end menu
-@node The alien-funcall Primitive, The define-alien-routine Macro, Foreign Function Calls, Foreign Function Calls
+@node The alien-funcall Primitive
@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
The @code{alien-funcall} function is the foreign function call
primitive: @var{alien-function} is called with the supplied
result)))
@end lisp
-@node The define-alien-routine Macro, define-alien-routine Example, The alien-funcall Primitive, Foreign Function Calls
+@node The define-alien-routine Macro
@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
The @code{define-alien-routine} macro is a convenience for
automatically generating Lisp interfaces to simple foreign functions.
@end defmac
-@node define-alien-routine Example, Calling Lisp From C, The define-alien-routine Macro, Foreign Function Calls
+@node define-alien-routine Example
@comment node-name, next, previous, up
@subsection @code{define-alien-routine} Example
The Lisp function @code{cfoo} will have two arguments (@var{str} and
@var{a}) and two return values (@var{a} and @var{i}).
-@node Calling Lisp From C, , define-alien-routine Example, Foreign Function Calls
+@node Calling Lisp From C
@comment node-name, next, previous, up
@subsection Calling Lisp From C
@c -->
-@node Step-By-Step Example of the Foreign Function Interface, , Foreign Function Calls, The Foreign Function Interface
+@node Step-By-Step Example of the Foreign Function Interface
@comment node-name, next, previous, up
@section Step-By-Step Example of the Foreign Function Interface
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";
@end lisp
To execute the above example, it is necessary to compile the C
-routine, e.g.: @samp{cc -c test.c} (In order to enable incremental
-loading with some linkers, you may need to say @samp{cc -G 0 -c
-test.c})
+routine, e.g.: @samp{cc -c test.c && ld -shared -o test.so test.o} (In
+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-foreign "test.o")}. 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