@c Generated by the sb-manual contrib. Do not edit.

@node foreign function interface
@chapter Foreign Function Interface

@menu
* Introduction to the Foreign Function Interface: introduction to the foreign function interface.
* Foreign Types: foreign types.
* Operations On Foreign Values: operations on foreign values.
* Foreign Variables: foreign variables.
* Foreign Data Structure Examples: foreign data structure examples.
* Loading Shared Object Files: loading shared object files.
* Foreign Function Calls: foreign function calls.
* Calling Lisp From C: calling lisp from c.
* Step-By-Step Example of the Foreign Function Interface: step by step example of the foreign function interface.
@end menu

This chapter describes SBCL's interface to C programs and
libraries (and, since C interfaces are a sort of @emph{lingua franca}
of the Unix world, to other programs and libraries in general).

@quotation
@emph{Note}: In the modern Lisp world, the usual term for this
functionality is Foreign Function Interface, or FFI, where despite
the mention of @emph{function} in this term, FFI also refers to direct
manipulation of C data structures as well as functions. The
traditional CMUCL terminology is Alien Interface, and while that
older terminology is no longer used much in the system
documentation, it still reflected in names in the implementation,
notably in the name of the @code{sb-alien} package.
@end quotation

@node introduction to the foreign function interface
@section Introduction to the Foreign Function Interface

Because of Lisp's emphasis on dynamic memory allocation and garbage
collection, Lisp implementations use non-C-like memory
representations for objects. This representation mismatch creates
friction when a Lisp program must share objects with programs which
expect C data. There are three common approaches to establishing
communication:

@itemize
@item The burden can be placed on the foreign program (and programmer)
  by requiring the knowledge and use of the representations used
  internally by the Lisp implementation. This can require a
  considerable amount of "glue" code on the C side, and that code
  tends to be sensitively 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 translation becomes prohibitively slow when large or complex
  data structures must be shared. This approach is supported by the
  SBCL FFI, and used automatically when passing integers and
  strings.

@item The Lisp program can directly manipulate foreign objects through
  the use of extensions to the Lisp language.
@end itemize

SBCL, like CMUCL before it, relies primarily on the automatic
conversion and direct manipulation approaches. The @code{sb-alien}
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 SAPs) can be used where
necessary to provide untyped access to foreign memory.

Any foreign objects that can't automatically be converted into Lisp
values are represented by objects of type
@code{sb-alien-internals:alien-value} Since Lisp is a dynamically typed
language, even foreign objects must have a run-time type; this type
information is provided by encapsulating the raw pointer to the
foreign data within an @code{sb-alien-internals:alien-value} object.

The type language and operations on foreign types are intentionally
similar to those of the C language.

@node foreign types
@section Foreign Types

@menu
* Defining Foreign Types: defining foreign types.
* Foreign Types and Lisp Types: foreign types and lisp types.
* Foreign Type Specifiers: foreign type specifiers.
@end menu

Alien types have a description language based on nested list
structure. For example the C type

@example
struct foo @{
    int a;
    struct foo *b[100];
@};
@end example

has the corresponding SBCL FFI type

@example
(struct foo
  (a int)
  (b (array (* (struct foo)) 100)))
@end example

@node defining foreign types
@subsection Defining Foreign Types

Types may be either named or anonymous. With structure and union
types, the name is part of the type specifier, allowing recursively
defined types such as:

@example
(struct foo (a (* (struct foo))))
@end example

An anonymous structure or union type is specified by using the name
@code{nil}. The @code{with-alien} macro defines a local scope which @emph{captures} any
named type definitions. Other types are not inherently named, but
can be given named abbreviations using the @code{define-alien-type} macro.

@node foreign types and lisp types
@subsection Foreign Types and Lisp Types

The foreign types form a subsystem of the SBCL type system. An
@code{alien} type specifier provides a way to use any foreign type as a
Lisp type specifier. For example,

@example
(typep foo '(alien (* int)))
@end example

can be used to determine whether @code{foo} is a pointer to a foreign
@code{int}. @code{alien} type specifiers can be used in the same ways as
ordinary Lisp type specifiers (like @code{string}.) Alien type declarations
are subject to the same precise type checking as any other
declaration. See @ref{precise type checking}.

Note that the type identifiers used in the foreign type system
overlap with native Lisp type specifiers in some cases. For example,
the type specifier @code{(alien single-float)} is identical to
@code{single-float}, since foreign floats are automatically converted to
Lisp floats. When @code{type-of} is called on an alien value that is not
automatically converted to a Lisp value, then it will return an
@code{alien} type specifier.

@node foreign type specifiers
@subsection Foreign Type Specifiers

@quotation
@emph{Note}: All foreign type names are exported from the @code{sb-alien}
package. Some foreign type names are also symbols in the
@code{common-lisp} package, in which case they are reexported from the
@code{sb-alien} package, so that e.g. it is legal to refer to
@code{single-float}.
@end quotation

These are the basic foreign type specifiers:

@itemize
@item The foreign type specifier @code{(* <foo>)} describes a pointer to an
  object of type @code{<foo>}. A pointed-to type @code{<foo>} of @code{t} indicates a
  pointer to anything, similar to @code{void *} in ANSI C. A null alien
  pointer can be detected with the @code{null-alien} function.

@item The foreign type specifier @code{(array <foo> &rest <dimensions>)}
  describes array of the specified @code{<dimensions>}, holding elements
  of type @code{<foo>}. Note that (unlike in C) @code{(* <foo>)} and
  @code{(array <foo>)} are considered to be different types when
  type checking is done. If equivalence of pointer and array types
  is desired, it may be explicitly coerced using @code{cast}.
@end itemize

Arrays are accessed using @code{deref}, passing the indices
as additional arguments.  Elements are stored in row-major order
(as in C), so the first dimension determines only the size of the
memory block, and not the layout of the higher dimensions. An array
whose first dimension is variable may be specified by using @code{nil} as
the first dimension. Fixed-size arrays can be allocated as array
elements, structure slots or @code{with-alien} variables. Dynamic arrays
can only be allocated using @code{make-alien}.

@cindex external format
@cindex format, external
@itemize
@item The foreign type specifier @code{(struct <name> &rest <fields>)}
  describes a structure type with the specified @code{<name>} and
  @code{<fields>}. Fields are allocated at the same offsets 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 @code{<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,
respectively, a new global or local foreign structure type. If
no @code{<fields>} are specified, then the fields are taken from the
current (local or global) alien structure type definition of
@code{<name>}.

@item The foreign type specifier @code{(union <name> &rest <fields>)} is
  similar to @code{struct} but describes a union type. All fields are
  allocated at the same offset, and the size of the union is the
  size of the largest field. The programmer must determine which
  field is active from context.

@item The foreign type specifier @code{(enum <name> &rest <specs>)} describes
  an enumeration type that maps between integer values and symbols.
  If @code{<name>} is @code{nil}, then the type is anonymous. Each element of
  the @code{<specs>} list is either a Lisp symbol, or a list
  @code{(<symbol> <value>)}. @code{<value>} is an integer. If @code{<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{(signed &optional <bits>)} specifies a
  signed integer with the specified number of @code{<bits>} precision.
  The upper limit on integer precision is determined by the
  machine's word size. If @code{<bits>} is not specified, the maximum
  size will be used.

@item The foreign type specifier @code{(integer &optional <bits>)} is
  equivalent to the corresponding type specifier using @code{signed}
  instead of @code{integer}.

@item The foreign type specifier @code{(unsigned &optional <bits>)} is like
  corresponding type specifier using @code{signed} except that the variable
  is treated as an unsigned integer.

@item The foreign type specifier @code{(boolean &optional <bits>)} is similar
  to an enumeration type but maps from Lisp @code{nil} and @code{t} to C 0 and 1
  respectively. @code{<bits>} determines the amount of storage allocated
  to hold the truth value.

@item The foreign type specifier @code{single-float} describes a
  floating-point number in IEEE single-precision format.

@item The foreign type specifier @code{double-float} describes a
  floating-point number in IEEE double-precision format.

@item The foreign type specifier @code{(function <result-type> &rest
  <arg-types>)} describes a foreign function that takes arguments of
  the specified @code{<arg-types>} and returns a result of type
  @code{<result-type>}. Note that the only context where a foreign
  @code{function} type is directly specified is in the argument to
  @code{alien-funcall}. In all other contexts, foreign functions are
  represented by foreign function pointer types: @code{(* (function
  ...))}.

@item The foreign type specifier @code{system-area-pointer} describes a
  pointer which is represented in Lisp as a @code{system-area-pointer}
  object. SBCL exports this type from @code{sb-alien} because CMUCL did,
  but tentatively (as of the first draft of this section of the
  manual, SBCL 0.7.6) it is deprecated, since it doesn't seem to be
  required by user code.

@item The foreign type specifier @code{void} is used in function types to
  declare that no useful value is returned. Using @code{alien-funcall} to
  call a @code{void} foreign function will return zero values.

@item The foreign type specifier @code{(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 0, then accessing it gives Lisp @code{nil} unless
  @code{<not-null>} is true, in which case a @code{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 @code{sb-ext:*default-c-string-external-format*} will be
used. For example, when the following alien routine is called,
the Lisp string given as argument is converted to an EBCDIC
octet representation.

@example
(define-alien-routine test int (str (c-string :external-format :ebcdic-us)))
@end example

Lisp strings of type @code{base-string} are stored with a trailing
@code{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
@code{<external-format>} and @code{<element-type>} are 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
pointed to by that variable. When a foreign object of type
@code{(* char)} is assigned to a @code{c-string}, then the @code{c-string} pointer
is assigned to. This allows @code{c-string} pointers to be initialized.
For example:

@example
(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"

(define-alien-type nil (struct foo (str c-string)))

(defun make-foo (str)
  (let ((my-foo (make-alien (struct foo))))
    (setf (slot my-foo 'str) (make-alien char (length str))
          (slot my-foo 'str) str)
    my-foo))
@end example

Storing Lisp @code{nil} in a @code{c-string} writes C @code{NULL} to the
variable.
@end itemize

@itemize
@item @code{sb-alien} also exports translations of these C type
@end itemize
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}, @code{off-t}

@node operations on foreign values
@section Operations On Foreign Values

@menu
* Accessing Foreign Values: accessing foreign values.
* Coercing Foreign Values: coercing foreign values.
* Foreign Dynamic Allocation: foreign dynamic allocation.
@end menu

This section describes how to read foreign values as Lisp values,
how to coerce foreign values to different kinds of foreign values,
and how to dynamically allocate and free foreign variables.

@node accessing foreign values
@subsection Accessing Foreign Values

@menu
* Untyped memory: untyped memory.
@end menu

@anchor{Function sb-alien deref}
@ffindex @sortas{deref sb-alien} deref [sb-alien]
@deffn{Function} sb-alien:deref alien &rest indices
Dereference an @code{alien} pointer or array. When dereferencing a pointer,
an optional single index can be specified to give the equivalent of
C pointer arithmetic; this index is scaled by the size of the type
pointed to. When dereferencing an array, the number of indices must
be the same as the number of dimensions in the array type. @code{setf}able.
@end deffn
@anchor{Function sb-alien slot}
@ffindex @sortas{slot sb-alien} slot [sb-alien]
@deffn{Function} sb-alien:slot alien slot
Extract the value of the slot named @code{slot} from a foreign @code{struct} or
@code{union} @code{alien}. If @code{alien} is a pointer to a structure or union, then it
is automatically dereferenced. @code{setf}able.

Note that @code{slot} is evaluated, and need not be a compile-time
constant (but only constant slot accesses are efficiently compiled).
@end deffn
@node untyped memory
@subsubsection Untyped memory

As noted at the beginning of the chapter, the System Area Pointer
facilities allow untyped access to foreign memory. SAPs can be
converted to and from the usual typed foreign values using @code{sap-alien}
and @code{alien-sap}, and also to and from integers (raw machine
addresses). They should thus be used with caution; corrupting the
Lisp heap or other memory with SAPs is trivial.

@anchor{Function sb-sys int-sap}
@ffindex @sortas{int-sap sb-sys} int-sap [sb-sys]
@deffn{Function} sb-sys:int-sap x
Creates a @code{sap} pointing at the virtual address @code{x}.
@end deffn
@anchor{Function sb-sys sap-ref-32}
@ffindex @sortas{sap-ref-32 sb-sys} sap-ref-32 [sb-sys]
@deffn{Function} sb-sys:sap-ref-32 sap offset
Access the value of the memory location at @code{offset} bytes from @code{sap}. @code{setf}able.
@end deffn
@anchor{Function sb-sys sap=}
@ffindex @sortas{sap= sb-sys} sap= [sb-sys]
@deffn{Function} sb-sys:sap= x y
Compare the @code{sap}s @code{x} and @code{y} for equality.
@end deffn
Similarly named functions exist for accessing other sizes of word,
other comparisons, and other conversions. The reader is invited to
use @code{apropos} and @code{describe} for more details:

@example
(apropos "sap" :sb-sys)
@end example

@node coercing foreign values
@subsection Coercing Foreign Values

@anchor{Macro sb-alien addr}
@ffindex @sortas{addr sb-alien} addr [sb-alien]
@deffn{Macro} sb-alien:addr expr
Return an Alien pointer to the data addressed by @code{expr},
which must be a foreign variable, a call to @code{deref} or @code{slot}, or a use
of @code{extern-alien}.
@end deffn
@anchor{Macro sb-alien cast}
@ffindex @sortas{cast sb-alien} cast [sb-alien]
@deffn{Macro} sb-alien:cast alien type
Convert @code{alien} to an Alien of the specified @code{type} (not evaluated).
Both types must be Alien array, pointer or function types.

Note that the resulting Lisp foreign variable object is not @code{eq} to
the argument, but it points to the same foreign memory address.
@end deffn
@anchor{Macro sb-alien sap-alien}
@ffindex @sortas{sap-alien sb-alien} sap-alien [sb-alien]
@deffn{Macro} sb-alien:sap-alien sap type
Convert the @code{system-area-pointer} @code{sap} to an @code{alien} of the specified
@code{type} (not evaluated). @code{type} must be pointer-like (foreign pointer,
array, or record type).
@end deffn
@anchor{Function sb-alien alien-sap}
@ffindex @sortas{alien-sap sb-alien} alien-sap [sb-alien]
@deffn{Function} sb-alien:alien-sap alien
Return a @code{system-area-pointer} pointing to @code{alien}'s data.
@code{alien} must be of some foreign pointer, array, or record type.
@end deffn
@node foreign dynamic allocation
@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 uses the same allocator as foreign C code, so it's
OK for foreign code to call @code{free} on the result of Lisp @code{make-alien},
or for Lisp code to call @code{free-alien} on foreign objects allocated by
C code.

@anchor{Macro sb-alien make-alien}
@ffindex @sortas{make-alien sb-alien} make-alien [sb-alien]
@deffn{Macro} sb-alien:make-alien type &optional size
Allocate an alien of type @code{type} in foreign heap, and return an alien
pointer to it. The allocated memory is not initialized, and may
contain garbage. The memory is allocated using @code{malloc(3)}, so it can
be passed to foreign functions which use @code{free(3)}, or released using
@code{free-alien}.

For alien stack allocation, see macro @code{with-alien}.

The @code{type} argument is not evaluated. If @code{size} is supplied, how it is
interpreted depends on @code{type}:

@itemize
@item When @code{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 first access the array through the pointer.

If supplied, @code{size} is used as the first dimension for the array.

@item When @code{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} @code{int}) returns a (* @code{int}).

If @code{size} is specified, then a block of that many objects is
allocated, with the result pointing to the first one.
@end itemize

Examples:

@example
(defvar *foo* (make-alien (array char 10)))
(type-of *foo*)                   ; => (alien (* (array (signed 8) 10)))
(setf (deref (deref *foo*) 0) 10) ; => 10

(make-alien char 12)              ; => (alien (* (signed 8)))
@end example
@end deffn
@anchor{Function sb-alien make-alien-string}
@ffindex @sortas{make-alien-string sb-alien} make-alien-string [sb-alien]
@deffn{Function} sb-alien:make-alien-string string &rest rest &key start end external-format null-terminate
Copy part of @code{string} delimited by @code{start} and @code{end} into freshly
allocated foreign memory, freeable using @code{free(3)} or @code{free-alien}.
Returns the allocated string as a (* @code{char}) alien, and the number of
bytes allocated as secondary value.

The string is encoded using @code{external-format}. If @code{null-terminate} is
true (the default), the alien string is terminated by an additional
null byte.
@end deffn
@anchor{Function sb-alien free-alien}
@ffindex @sortas{free-alien sb-alien} free-alien [sb-alien]
@deffn{Function} sb-alien:free-alien alien
Dispose of the storage pointed to by @code{alien}. The @code{alien} must have been
allocated by @code{make-alien}, @code{make-alien-string} or @code{malloc(3)}.
@end deffn
@node foreign variables
@section Foreign Variables

@menu
* Local Foreign Variables: local foreign variables.
* External Foreign Variables: external foreign variables.
@end menu

Both local (stack allocated) and external (C global) foreign
variables are supported.

@node local foreign variables
@subsection Local Foreign Variables

@anchor{Macro sb-alien with-alien}
@ffindex @sortas{with-alien sb-alien} with-alien [sb-alien]
@deffn{Macro} sb-alien:with-alien bindings &body body
Establish some local alien variables of dynamic extent.
Each of @code{bindings} is of the form:

@example
 VAR TYPE [ ALLOCATION ] [ INITIAL-VALUE | EXTERNAL-NAME ]
@end example

 @code{allocation} should be one of:

@itemize
@item @code{:local} (the default): The alien is allocated on the stack, and
     has dynamic extent.

@item @code{:extern}: No alien is allocated, but @code{var} is established as a
     local name for the external alien given by @code{external-name}.
@end itemize

@code{var}s are established as symbol-macros; the bindings have lexical
scope, and may be assigned with @code{setq} or @code{setf}.

The @code{with-alien} macro also establishes a new scope for named
structures and unions. Any @code{type} specified for a variable may contain
named structure or union types with the slots specified. Within the
lexical scope of the binding specifiers and body, a locally defined
foreign structure type @code{foo} can be referenced by its name using
@code{(struct foo)}.

When a foreign function returns a structure by value, using
@code{alien-funcall} as the @code{initial-value} allows the returned struct to
be stack-allocated directly into the local variable's storage,
avoiding heap allocation:

@example
(with-alien ((result (struct point)
                     (alien-funcall
                      (extern-alien "make_point"
                                    (function (struct point) double double))
                      1.0d0 2.0d0)))
  (values (slot result 'x) (slot result 'y)))
@end example
@end deffn
@node external foreign variables
@subsection External Foreign Variables

External foreign names are strings, and Lisp names are symbols. When
an external foreign value is represented using a Lisp variable, there
must be a way to convert from one name syntax into the other. The
macros @code{extern-alien}, @code{define-alien-variable} and
@code{define-alien-routine} use this conversion heuristic:

@itemize
@item Alien names are converted to Lisp names by uppercasing and
  replacing underscores with hyphens.

@item Conversely, Lisp names are converted to alien names by lowercasing
  and replacing hyphens with underscores.

@item Both the Lisp symbol and alien string names may be separately
  specified by using a list of the form

@example
(<alien-string> <lisp-symbol>)
@end example
@end itemize

@anchor{Macro sb-alien define-alien-variable}
@ffindex @sortas{define-alien-variable sb-alien} define-alien-variable [sb-alien]
@deffn{Macro} sb-alien:define-alien-variable name type
Define @code{name} as an external alien variable of type @code{type}.
Neither is evaluated.

In its full form, @code{name} is @code{(<alien-name-string>
<lisp-name-symbol>)}. If @code{name} is just a symbol or string, then the
other name is guessed from the one supplied as described
@ref{external foreign variables}.

The Lisp name of the variable becomes a global alien variable.
Global alien variables are effectively "global symbol macros"; a
reference to the variable fetches the contents of the external
variable. Similarly, setting the variable stores new contents -- the
new contents must be of the declared @code{type}. Someday, they may well be
implemented using the ANSI @code{define-symbol-macro} mechanism, but as of
SBCL 0.7.5, they are still implemented using an older more-or-less
parallel mechanism inherited from CMUCL.

For example, to access a C-level counter @code{foo}, one could write

@example
(define-alien-variable "foo" int)
;; Now it is possible to get the value of the C variable foo simply by
;; referencing that Lisp variable:
(print foo)
(setf foo 14)
(incf foo)
@end example
@end deffn
@anchor{Function sb-alien get-errno}
@ffindex @sortas{get-errno sb-alien} get-errno [sb-alien]
@deffn{Function} sb-alien:get-errno
Return the value of the C library pseudo-variable named @code{errno}.

Since in modern C libraries, @code{errno} is typically no longer a
variable, but some bizarre artificial construct which behaves
superficially like a variable within a given thread, it can no longer
reliably be accessed through the ordinary @code{define-alien-variable}
mechanism.
@end deffn
@anchor{Macro sb-alien extern-alien}
@ffindex @sortas{extern-alien sb-alien} extern-alien [sb-alien]
@deffn{Macro} sb-alien:extern-alien name type
Return an alien of @code{type} which points to an externally defined value of @code{name}.
@code{name} is not evaluated and may be either a string or a symbol. @code{type}
is an unevaluated alien type specifier. @code{setf}able.
@end deffn
@node foreign data structure examples
@section Foreign Data Structure Examples

Now that we have alien types, operations and variables, we can
manipulate foreign data structures. This C declaration

@example
struct foo @{
    int a;
    struct foo *b[100];
@};
@end example

can be translated into the following alien type:

@example
(define-alien-type nil
  (struct foo
    (a int)
    (b (array (* (struct foo)) 100))))
@end example

Once the @code{foo} alien type has been defined as above, the C
expression

@example
struct foo f;
f.b[7].a;
@end example

can be translated in this way:

@example
(with-alien ((f (struct foo)))
  (slot (deref (slot f 'b) 7) 'a)
  ;;
  ;; Do something with f...
  )
@end example

Or consider this example of an external C variable and some accesses:

@example
struct c_struct @{
        short x, y;
        char a, b;
        int z;
        c_struct *n;
@};
extern struct c_struct *my_struct;
my_struct->x++;
my_struct->a = 5;
my_struct = my_struct->n;
@end example

which can be manipulated in Lisp like this:

@example
(define-alien-type nil
  (struct c-struct
          (x short)
          (y short)
          (a char)
          (b char)
          (z int)
          (n (* c-struct))))
(define-alien-variable "my_struct" (* c-struct))
(incf (slot my-struct 'x))
(setf (slot my-struct 'a) 5)
(setq my-struct (slot my-struct 'n))
@end example

@node loading shared object files
@section Loading Shared Object Files

Foreign object files can be loaded into the running Lisp process by
calling @code{load-shared-object}.

@anchor{Function sb-alien load-shared-object}
@ffindex @sortas{load-shared-object sb-alien} load-shared-object [sb-alien]
@deffn{Function} sb-alien:load-shared-object pathname &key dont-save
Load a shared library / dynamic shared object file / similar foreign
container specified by designated @code{pathname}, such as a .so on an ELF platform.

Locating the shared object follows standard rules of the platform, consult the
manual page for @code{dlopen(3)} for details. Typically paths specified by
environment variables such as LD@emph{LIBRARY}PATH are searched if the @code{pathname} has
no directory, but on some systems (eg. Mac OS X) search may happen even if
@code{pathname} is absolute. (On Windows LoadLibrary is used instead of @code{dlopen(3)}.)

On non-Windows platforms calling @code{load-shared-object} again with a @code{pathname}
@code{equal} to the designated pathname of a previous call will replace the old
definitions; if a symbol was previously referenced through the object and
is not present in the reloaded version an error will be signalled. Reloading
may not work as expected if user or library-code has called @code{dlopen(3)} on the
same shared object or running on a system where @code{dlclose(3)} is a noop.

@code{load-shared-object} interacts with @code{sb-ext:save-lisp-and-die}:

1. If @code{dont-save} is true (default is @code{nil}), the shared object will be dropped
when @code{save-lisp-and-die} is called -- otherwise shared objects are reloaded
automatically when a saved core starts up. Specifying @code{dont-save} can be useful
when the location of the shared object on startup is uncertain.

2. On most platforms references in compiled code to foreign symbols in shared
objects (such as those generated by @code{define-alien-routine}) remain valid across
@code{save-lisp-and-die}. On those platforms where this is not supported, a @code{warning}
will be signalled when the core is saved -- this is orthogonal from @code{dont-save}.
@end deffn
@anchor{Function sb-alien unload-shared-object}
@ffindex @sortas{unload-shared-object sb-alien} unload-shared-object [sb-alien]
@deffn{Function} sb-alien:unload-shared-object pathname
Unloads the shared object loaded earlier using the designated @code{pathname} with
@code{load-shared-object}, to the degree supported on the platform.

Experimental.
@end deffn
@node foreign function calls
@section Foreign Function Calls

The foreign function call interface allows a Lisp program to call
many functions written in languages that use the C calling convention.

Lisp sets up various signal handling routines and other environment
information when it first starts up, and expects these to be in
place at all times. The C functions called by Lisp should not change
the environment, especially the signal handlers: the signal handlers
installed by Lisp typically have interesting flags set (e.g to
request machine context information, or for signal delivery on an
alternate stack) which the Lisp runtime relies on for correct
operation. Precise details of how this works may change without
notice between versions; the source, or the brain of a friendly SBCL
developer, is the only documentation. Users of a Lisp built with the
@code{:sb-thread} feature should also read the section about threads,
@ref{threading}.

@anchor{Function sb-alien alien-funcall}
@ffindex @sortas{alien-funcall sb-alien} alien-funcall [sb-alien]
@deffn{Function} sb-alien:alien-funcall alien &rest args
Call the foreign function @code{alien} with @code{args} and return its C return value
as a Lisp value. @code{alien}'s foreign type specifies the argument and
result types. @code{alien} is typically an @code{extern-alien} or a value defined
with @code{define-alien-routine}.

The type of @code{alien} must be @code{(alien (function ...))} or @code{(alien
(* (function ...)))}. The function type is used to determine how to
call the function (as though it was declared with a prototype). The
type need not be known at compile time, but only known-type calls
are efficiently compiled.

On Unix-like x86-64 and ARM64 systems, structures may be passed and
returned by value. The implementation follows the System V AMD64 ABI
and AAPCS64 specifications respectively.

Here is an example which allocates a @code{(struct foo)}, calls a foreign
function to initialize it, then returns a Lisp vector of all
the @code{(* (struct foo))} objects filled in by the foreign call:

@example
;; Allocate a foo on the stack.
(with-alien ((f (struct foo)))
  ;; Call some C function to fill in foo fields.
  (alien-funcall (extern-alien "mangle_foo" (function void (* foo)))
                 (addr f))
  ;; Find how many foos to use by getting the A field.
  (let* ((num (slot f 'a))
         (result (make-array num)))
    ;; Get a pointer to the array so that we don't have to keep extracting it:
    (with-alien ((a (* (array (* (struct foo)) 100)) (addr (slot f 'b))))
      ;; Loop over the first N elements and stash them in the result vector.
      (dotimes (i num)
        (setf (svref result i) (deref (deref a) i)))
      ;; Voila.
      result)))
@end example
@end deffn
@anchor{Function sb-alien alien-funcall-into}
@ffindex @sortas{alien-funcall-into sb-alien} alien-funcall-into [sb-alien]
@deffn{Function} sb-alien:alien-funcall-into alien result-buffer &rest args
Call the foreign function @code{alien}, writing the struct result to @code{result-buffer}.
Returns no values.

@code{result-buffer} should be a @code{system-area-pointer} to appropriately sized memory.
Only supported on x86-64 and ARM64.

Here is an example that calls a C function returning a struct, writing
the result to a stack-allocated buffer:

@example
(define-alien-type nil (struct point (x double) (y double)))

(with-alien ((result (struct point)))
  (alien-funcall-into
   (extern-alien "make_point"
                 (function (struct point) double double))
   (alien-sap (addr result))
   1.0d0 2.0d0)
  (values (slot result 'x) (slot result 'y)))
@end example
@end deffn
@anchor{Macro sb-alien define-alien-routine}
@ffindex @sortas{define-alien-routine sb-alien} define-alien-routine [sb-alien]
@deffn{Macro} sb-alien:define-alien-routine name result-type &rest args
Define a foreign interface function for the routine with the specified @code{name}.
Also automatically @code{declaim} the @code{ftype} of the defined function. The
semantics of the actual call are the same as for @code{alien-funcall}.

This macro is a convenience for automatically generating Lisp
interfaces to simple foreign functions. The primary feature is the
parameter style specification, which translates the C
pass-by-reference idiom into additional return values.

@code{name} may be either a string, a symbol, or a list of the
form @code{(<foreign-name-string> <lisp-name-symbol>)}.

@code{result-type} is the alien type for the function return value. @code{void} may be
used to specify a function with no result.

@code{args} is a list of @code{(arg-name arg-type &optional style)} elements.
@code{arg-name} is a symbol that names the argument, primarily for
documentation. @code{arg-type} is the C type of the argument.

@code{style} specifies the way that the argument is passed:

@itemize
@item @code{:in}: An @code{:in} argument is simply passed by value. The value to be
  passed is obtained from argument(s) to the interface function. No
  values are returned for @code{:in} arguments. This is the default mode.

@item @code{:out}: A pass-by-reference output value. The specified argument type
  must be a pointer to a fixed sized object. An object of the correct
  size is allocated on the stack, and its address is passed to the
  foreign function. When the function returns, the contents of this
  location are returned as one of the values of the Lisp function (and
  the location is automatically deallocated). @code{:out} and @code{:in-out} cannot
  be used with pointers to arrays, records or functions.

@item @code{:copy}: This is similar to @code{:in}, except that the argument values are
  stored on the stack, and a pointer to the object is passed instead
  of the value itself.

@item @code{:in-out}: This is a combination of @code{:out} and @code{:copy}. A pointer to the
  argument is passed, with the object being initialized from the
  supplied argument and the return value being determined by accessing
  the object on return.
@end itemize

@quotation
@emph{Note}: Any efficiency-critical foreign interface function should be
inline expanded, which can be done by preceding the
@code{define-alien-routine} call with:

@example
(declaim (inline lisp-name))
@end example

In addition to avoiding the Lisp call overhead, this allows
pointers, word-integers and floats to be passed using non-descriptor
representations, avoiding consing.
@end quotation

Consider the C function @code{cfoo} with the following calling
convention:

@example
void
cfoo (str, a, i)
    char *str;
    char *a; /* update */
    int *i; /* out */
@{
  /* body of cfoo(...) */
@}
@end example

This can be described by the following call to @code{define-alien-routine}:

@example
(define-alien-routine "cfoo" void
  (str c-string)
  (a char :in-out)
  (i int :out))
@end example

The Lisp function @code{cfoo} will have two arguments (@code{str} and @code{a}) and
two return values (@code{a} and @code{i}).
@end deffn
@node calling lisp from c
@section Calling Lisp From C

@menu
* Lisp as a Shared Library: lisp as a shared library.
@end menu

SBCL supports the calling of Lisp functions using the C calling
convention. This is useful for both defining callbacks and for creating
an interface for calling into Lisp as a shared library directly from C.

The @code{define-alien-callable} macro wraps Lisp code and creates a C
foreign function which can be called with the C calling convention.
On x86-64 and ARM64, callbacks may receive and return structures by
value.

@anchor{Macro sb-alien define-alien-callable}
@ffindex @sortas{define-alien-callable sb-alien} define-alien-callable [sb-alien]
@deffn{Macro} sb-alien:define-alien-callable name result-type typed-lambda-list &body body
Define an alien function which can be called by alien code. The alien
function returned by (@code{alien-callable-function} @code{name}) expects alien
arguments of the specified @code{arg-type}s and returns an alien of type
@code{result-type}.

@code{typed-lambda-list} is a list of @code{(arg-name arg-type)} elements, and
@code{body} is @code{@{doc-string@} @{decl@}* @{form@}*}.

If (@code{alien-callable-function} @code{name}) already exists, its value is not
changed (though it is arranged that an updated version of the Lisp
callable function will be called, provided that the new type and the
existing type are compatible). This feature allows for incremental
redefinition of callable functions.
@end deffn
The @code{alien-callable-function} function returns the foreign callable
value associated with any name defined by @code{define-alien-callable}, so
that we can, for example, pass the callable value to C as a
callback.

@anchor{Function sb-alien alien-callable-function}
@ffindex @sortas{alien-callable-function sb-alien} alien-callable-function [sb-alien]
@deffn{Function} sb-alien:alien-callable-function name
Return the alien callable function associated with @code{name}.
@end deffn
The @code{with-alien-callable} macro wraps Lisp code and establishes
local C foreign functions which can be called with the C calling
convention. This macro is handy for passing callbacks which close over
Lisp values into C.

@anchor{Macro sb-alien with-alien-callable}
@ffindex @sortas{with-alien-callable sb-alien} with-alien-callable [sb-alien]
@deffn{Macro} sb-alien:with-alien-callable definitions &body body
Establish some local alien functions.
Each element of @code{definitions} is of the form:

@example
NAME RESULT-TYPE @{(ARG-NAME ARG-TYPE)@}* @{DOC-STRING@} @{DECL@}* @{FORM@}*
@end example

The resulting alien callable value has dynamic extent.
@end deffn
Note that the garbage collector moves objects, and won't be able to fix
up any references in C variables. There are three mechanisms for
coping with this:

@cindex garbage collector, generational
@cindex generational garbage collector
@itemize
@item @code{sb-ext:purify} moves all live Lisp data into static or read-only
  areas such that it will never be moved (or freed) again in the
  life of the Lisp session

@item @code{sb-sys:with-pinned-objects} is a macro which arranges for some set
  of objects to be pinned in memory for the dynamic extent of its
  body forms. On ports which use the generational GC
  (most, as of this writing) this affects exactly the specified
  objects. On other ports it is implemented by turning off GC for
  the duration (so could be said to have a whole-world granularity).

@item Disable GC, using the SB-EXT:WITHOUT-GCING macro.
@end itemize

@node lisp as a shared library
@subsection Lisp as a Shared Library

SBCL supports the use of Lisp as a shared library that can be used by
C programs using the @code{define-alien-callable} interface. See the
@code{:callable-exports} argument of @code{sb-ext:save-lisp-and-die} for how to
save the Lisp image in a way that allows a C program to initialize
the Lisp runtime and the exported symbols. When SBCL is built as a
library, it exposes the symbol @code{initialize_lisp} which can be used
in conjunction with a core initializing global symbols to foreign
callables as function pointers and with object code allocating those
symbols to initialize the runtime properly. The arguments to
@code{initialize_lisp} are the same as the arguments to the main @code{sbcl}
program.

@quotation
@emph{Note}: There is currently no way to run exit hooks or otherwise
undo Lisp initialization gracefully from C.
@end quotation

@node step by step example of the foreign function interface
@section Step-By-Step Example of the Foreign Function Interface

This section presents a complete example of an interface to a somewhat
complicated C function.

Suppose you have the following C function which you want to be able
to call from Lisp in the file @code{test.c}:

@example
struct c_struct
@{
  int x;
  char *s;
@};

struct c_struct *c_function (i, s, r, a)
    int i;
    char *s;
    struct c_struct *r;
    int a[10];
@{
  int j;
  struct c_struct *r2;

  printf("i = %dn", i);
  printf("s = %sn", s);
  printf("r->x = %dn", r->x);
  printf("r->s = %sn", r->s);
  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";
  return(r2);
@};
@end example

It is possible to call this C function from Lisp using the file
@code{test.lisp} containing

@example
(cl:defpackage "TEST-C-CALL" (:use "CL" "SB-ALIEN" "SB-C-CALL"))
(cl:in-package "TEST-C-CALL")

;;; Define the record C-STRUCT in Lisp.
(define-alien-type nil
    (struct c-struct
            (x int)
            (s c-string)))

;;; Define the Lisp function interface to the C routine.  It returns a
;;; pointer to a record of type C-STRUCT.  It accepts four parameters:
;;; I, an int; S, a pointer to a string; R, a pointer to a C-STRUCT
;;; record; and A, a pointer to the array of 10 ints.
;;;
;;; The INLINE declaration eliminates some efficiency notes about heap
;;; allocation of alien values.
(declaim (inline c-function))
(define-alien-routine c-function
    (* (struct c-struct))
  (i int)
  (s c-string)
  (r (* (struct c-struct)))
  (a (array int 10)))

;;; a function which sets up the parameters to the C function and
;;; actually calls it
(defun call-cfun ()
  (with-alien ((ar (array int 10))
               (c-struct (struct c-struct)))
    (dotimes (i 10)                     ; Fill array.
      (setf (deref ar i) i))
    (setf (slot c-struct 'x) 20)
    (setf (slot c-struct 's) "a Lisp string")

    (with-alien ((res (* (struct c-struct))
                      (c-function 5 "another Lisp string" (addr c-struct) ar)))
      (format t "~&back from C function~%")
      (multiple-value-prog1
          (values (slot res 'x)
                  (slot res 's))

        ;; Deallocate result. (after we are done referring to it:
        ;; "Pillage, *then* burn.")
        (free-alien res)))))
@end example

To execute the above example, it is necessary to compile the C
routine, e.g. with @code{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 @code{cc -G 0 -c test.c}.

Once the C code has been compiled, you can start up Lisp and load it
in: @code{sbcl}. Lisp should start up with its normal prompt.

Within Lisp, compile the Lisp file:

@example
(compile-file "test.lisp")
@end example

This step can be done separately. You don't have to recompile every
time.

Within Lisp, load the foreign object file to define the necessary
symbols:

@example
(load-shared-object "test.so")
@end example

Now you can load the compiled Lisp (fasl) file into Lisp:

@example
(load "test.fasl")
@end example

And once the Lisp file is loaded, you can call the Lisp routine
that sets up the parameters and calls the C function:

@example
(test-c-call::call-cfun)
@end example

The C routine should print the following information to standard output:

@example
i = 5
s = another Lisp string
r->x = 20
r->s = a Lisp string
a[0] = 0.
a[1] = 1.
a[2] = 2.
a[3] = 3.
a[4] = 4.
a[5] = 5.
a[6] = 6.
a[7] = 7.
a[8] = 8.
a[9] = 9.
@end example

After return from the C function,
the Lisp wrapper function should print the following output:

@example
back from C function
@end example

And upon return from the Lisp wrapper function,
before the next prompt is printed, the
Lisp read-eval-print loop should print the following return values:

@example
10
"a C string"
@end example

