X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fffi.texinfo;h=b65b2bc174617ac92fb9169a3c64a7a2b4988f96;hb=3cd07d95709e7059ed76076e9978ac21bd5b3629;hp=ea1399572d271c3c4cea4e9f6143c5a915d5f445;hpb=7b5628003e3016985952908016219b872ed48811;p=sbcl.git diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo index ea13995..b65b2bc 100644 --- a/doc/manual/ffi.texinfo +++ b/doc/manual/ffi.texinfo @@ -3,7 +3,7 @@ @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.) @@ -64,7 +64,7 @@ use of extensions to the Lisp language. 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 @@ -196,8 +196,10 @@ variables. Dynamic arrays can only be allocated using 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, @@ -281,15 +283,37 @@ types to declare that no useful value is returned. Using 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 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. +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 @@ -357,7 +381,7 @@ 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 @@ -438,12 +462,12 @@ argument, but it does refer to the same foreign data bits. 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. +@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} +@defun sb-alien:alien-sap @var{foreign-value} @findex alien-sap The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which @@ -945,8 +969,7 @@ 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 @code{without-gcing} macro or @code{gc-off} -call. +Disable GC, using the @code{without-gcing} macro. @end enumerate @c