-@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
* 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
@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
@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).
@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
+@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}. 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; strings
+of type @code{(simple-array character (*))} are 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
(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 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
@comment node-name, next, previous, up
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")}