1.0.29.31: new contrib: SB-QUEUE

[sbcl.git] / doc / manual / ffi.texinfo

diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index c8bc8d5..b65b2bc 100644 (file)
--- 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
 @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.)
 
 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}
 
 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
 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
 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,
 
 If a named foreign @code{struct} specifier is passed to
 @code{define-alien-type} or @code{with-alien}, then this defines,

@@ -281,13 +283,37 @@ types to declare that no useful value is returned.  Using
 return zero values.
 
 @item
 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
 
 Assigning a Lisp string to a @code{c-string} structure field or
 variable stores the contents of the string to the memory already

@@ -355,7 +381,7 @@ array type. @code{deref} can be set with @code{setf} to assign a new
 value.
 @end defun
 
 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
 @findex slot
 
 The @code{sb-alien:slot} function extracts the value of the slot named

@@ -436,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
 
 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
 
 
 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
 @findex alien-sap
 
 The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which

@@ -943,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
 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.
 @end enumerate
 
 @c <!-- FIXME: This is a "changebar" section from the CMU CL manual.

@@ -1182,8 +1207,8 @@ 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})
 
 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.)
 
 Within Lisp, compile the Lisp file. (This step can be done
 separately. You don't have to recompile every time.)