fix typo in FFI chapter

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

diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index 354e659..0c4eb49 100644 (file)
--- a/doc/manual/ffi.texinfo
+++ b/doc/manual/ffi.texinfo
@@ -49,12 +49,11 @@ by the Lisp implementation.  This can require a considerable amount of
 dependent on the internal implementation details of the Lisp system.
 
 @item
 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
+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
 translation becomes prohibitively slow when large or complex data
 structures must be shared. This approach is supported by the SBCL

-@acronym{FFI}, and used automatically by the when passing integers and
-strings.
+@acronym{FFI}, and used automatically when passing integers and strings.

 
 @item
 The Lisp program can directly manipulate foreign objects through the
 
 @item
 The Lisp program can directly manipulate foreign objects through the

@@ -64,7 +63,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 +195,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,15 +282,40 @@ 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
+@cindex External formats
+The foreign type specifier @code{(sb-alien: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 @code{0}, then accessing it gives Lisp
 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.
+@code{nil} unless @code{not-null} is true, in which case a 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 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

@@ -315,13 +341,17 @@ the variable.
 
 @item
 @code{sb-alien} also exports translations of these C type
 
 @item
 @code{sb-alien} also exports translations of these C type

-specifiers as foreign type specifiers: @code{sb-alien:char},
-@code{sb-alien:short}, @code{sb-alien:int},
-@code{sb-alien:long}, @code{sb-alien:unsigned-char},
-@code{sb-alien:unsigned-short},
-@code{sb-alien:unsigned-int},
-@code{sb-alien:unsigned-long}, @code{sb-alien:float}, and
-@code{sb-alien:double}.
+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}, and @code{off-t}.

 
 @end itemize
 
 
 @end itemize
 

@@ -344,8 +374,7 @@ to dynamically allocate and free foreign variables.
 @comment  node-name,  next,  previous,  up
 @subsection 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
+@defun @sbalien{deref} @var{pointer-or-array} &rest @var{indices}

 
 The @code{sb-alien:deref} function returns the value pointed to by a
 foreign pointer, or the value of a foreign array element. When
 
 The @code{sb-alien:deref} function returns the value pointed to by a
 foreign pointer, or the value of a foreign array element. When

@@ -357,8 +386,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}
-@findex slot
+@defun @sbalien{slot} @var{struct-or-union} @var{slot-name}

 
 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
 
 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

@@ -380,23 +408,20 @@ to and from integers - raw machine addresses.  They should thus be
 used with caution; corrupting the Lisp heap or other memory with
 @acronym{SAP}s is trivial.
 
 used with caution; corrupting the Lisp heap or other memory with
 @acronym{SAP}s is trivial.
 

-@defun sb-sys:int-sap @var{machine-address}
-@findex int-sap
+@defun @sbsys{int-sap} @var{machine-address}

 
 Creates a @acronym{SAP} pointing at the virtual address
 @var{machine-address}.
 @end defun
 
 
 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
+@defun @sbsys{sap-ref-32} @var{sap} @var{offset}

 
 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
 memory at that location.
 @end defun
 
 
 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
 memory at that location.
 @end defun
 

-@defun sb-sys:sap= @var{sap1} @var{sap2}
-@findex sap=
+@defun @sbsys{sap=} @var{sap1} @var{sap2}

 
 Compare @var{sap1} and @var{sap2} for equality.
 @end defun
 
 Compare @var{sap1} and @var{sap2} for equality.
 @end defun

@@ -414,37 +439,33 @@ use @code{apropos} and @code{describe} for more details
 @comment  node-name,  next,  previous,  up
 @subsection Coercing Foreign Values
 
 @comment  node-name,  next,  previous,  up
 @subsection Coercing Foreign Values
 

-@defun sb-alien:addr @var{alien-expr}
-@findex addr
+@defmac @sbalien{addr} @var{alien-expr}

 
 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
 @code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.
 
 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
 @code{sb-alien:slot}, or a use of @code{sb-alien:extern-alien}.

-@end defun
+@end defmac

 
 

-@defun sb-alien:cast @var{foreign-value} @var{new-type}
-@findex cast
+@defmac @sbalien{cast} @var{foreign-value} @var{new-type}

 
 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
 resulting Lisp foreign variable object is not @code{eq} to the
 argument, but it does refer to the same foreign data bits.
 
 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
 resulting Lisp foreign variable object is not @code{eq} to the
 argument, but it does refer to the same foreign data bits.

-@end defun
+@end defmac

 
 

-@defun sb-alien:sap-alien @var{sap} @var{type}
-@findex sap-alien
+@defmac @sbalien{sap-alien} @var{sap} @var{type}

 
 

-The @code{sb-alien:sap-alien} function converts @var{sap} (a system
+The @code{sb-alien:sap-alien} macro converts @var{sap} (a system

 area pointer) to a foreign value with the specified
 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.
 
 The @var{type} must be some foreign pointer, array, or record type.

-@end defun
+@end defmac

 
 

-@defun sb-alien:alien-sap @var{foreign-value} @var{type}
-@findex alien-sap
+@defun @sbalien{alien-sap} @var{foreign-value}

 
 The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
 points to @var{alien-value}'s data.
 
 The @code{sb-alien:alien-sap} function returns the @acronym{SAP} which
 points to @var{alien-value}'s data.

@@ -459,62 +480,15 @@ record type.
 @subsection Foreign Dynamic Allocation
 
 Lisp code can call the C standard library functions @code{malloc} and
 @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 shares the same allocator with foreign C
-code, so it's OK for foreign code to call @code{free} on the result of
-Lisp @code{sb-alien:make-alien}, or for Lisp code to call
-@code{sb-alien:free-alien} on foreign objects allocated by C
-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
-initialized, and may contain arbitrary junk.  If supplied,
-@var{size} is an expression to evaluate to compute the size of the
-allocated object.  There are two major cases:
-
-@itemize
-@item
-When @var{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 change the result to an array before you can use
-@code{deref} to read or write elements:
-
-@lisp
-(cl:in-package "CL-USER") ; which USEs package "SB-ALIEN"
-(defvar *foo* (make-alien (array char 10)))
-(type-of *foo*) @result{} (alien (* (array (signed 8) 10)))
-(setf (deref (deref foo) 0) 10) @result{} 10
-@end lisp
-
-If supplied, @var{size} is used as the first dimension for the
-    array.
-
-@item
-When @var{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 int)} returns a @code{(* int)}.  If @var{size} is
-specified, then a block of that many objects is allocated, with the
-result pointing to the first one.
-
-@end itemize
-
-@end defmac
-
-@defun sb-alien:free-alien @var{foreign-value}
-@findex free-alien
+@code{free} to dynamically allocate and deallocate foreign variables.
+The Lisp code shares the same allocator with foreign C code, so it's
+OK for foreign code to call @code{free} on the result of Lisp
+@code{sb-alien:make-alien}, or for Lisp code to call
+@code{sb-alien:free-alien} on foreign objects allocated by C code.

 
 

-The @code{sb-alien:free-alien} function
-frees the storage for @var{foreign-value}, 
-which must have been allocated with Lisp @code{make-alien}
-or C @code{malloc}.
-
-See also the @code{sb-alien:with-alien} macro, which allocates foreign
-values on the stack.
-@end defun
+@include macro-sb-alien-make-alien.texinfo
+@include fun-sb-alien-make-alien-string.texinfo
+@include fun-sb-alien-free-alien.texinfo

 
 @node  Foreign Variables
 @comment  node-name,  next,  previous,  up
 
 @node  Foreign Variables
 @comment  node-name,  next,  previous,  up

@@ -533,8 +507,7 @@ are supported.
 @comment  node-name,  next,  previous,  up
 @subsection 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
+@defmac @sbalien{with-alien} @var{var-definitions} &body @var{body}

 
 The @code{with-alien} macro establishes local foreign variables with
 the specified alien types and names.  This form is analogous to
 
 The @code{with-alien} macro establishes local foreign variables with
 the specified alien types and names.  This form is analogous to

@@ -592,8 +565,7 @@ specified by using a list of the form
 
 @end itemize
 
 
 @end itemize
 

-@defmac sb-alien:define-alien-variable @var{name} @var{type}
-@findex define-alien-variable
+@defmac @sbalien{define-alien-variable} @var{name} @var{type}

 
 The @code{define-alien-variable} macro defines @var{name} as an
 external foreign variable of the specified foreign @code{type}.
 
 The @code{define-alien-variable} macro defines @var{name} as an
 external foreign variable of the specified foreign @code{type}.

@@ -619,8 +591,7 @@ For example, to access a C-level counter @var{foo}, one could write
 @end lisp
 @end defmac
 
 @end lisp
 @end defmac
 

-@defun sb-alien:get-errno
-@findex get-errno
+@defun @sbalien{get-errno}

 
 Since in modern C libraries, the @code{errno} ``variable'' is typically
 no longer a variable, but some bizarre artificial construct
 
 Since in modern C libraries, the @code{errno} ``variable'' is typically
 no longer a variable, but some bizarre artificial construct

@@ -630,8 +601,7 @@ it can no longer reliably be accessed through the ordinary
 the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
 @end defun
 
 the operator @code{sb-alien:get-errno} to allow Lisp code to read it.
 @end defun
 

-@defmac sb-alien:extern-alien @var{name} @var{type}
-@findex extern-alien
+@defmac @sbalien{extern-alien} @var{name} @var{type}

 
 The @code{extern-alien} macro returns an alien with the specified
 @var{type} which points to an externally defined value.  @var{name} is
 
 The @code{extern-alien} macro returns an alien with the specified
 @var{type} which points to an externally defined value.  @var{name} is

@@ -722,6 +692,8 @@ calling @code{load-shared-object}.
 
 @include fun-sb-alien-load-shared-object.texinfo
 
 
 @include fun-sb-alien-load-shared-object.texinfo
 

+@include fun-sb-alien-unload-shared-object.texinfo
+

 @node  Foreign Function Calls
 @comment  node-name,  next,  previous,  up
 @section Foreign Function Calls
 @node  Foreign Function Calls
 @comment  node-name,  next,  previous,  up
 @section Foreign Function Calls

@@ -753,8 +725,7 @@ the only documentation.  Users of a Lisp built with the
 @comment  node-name,  next,  previous,  up
 @subsection The @code{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
+@defun @sbalien{alien-funcall} @var{alien-function} &rest @var{arguments}

 
 The @code{alien-funcall} function is the foreign function call
 primitive: @var{alien-function} is called with the supplied
 
 The @code{alien-funcall} function is the foreign function call
 primitive: @var{alien-function} is called with the supplied

@@ -807,8 +778,7 @@ the @code{(* (struct foo))} objects filled in by the foreign call:
 @comment  node-name,  next,  previous,  up
 @subsection The @code{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
+@defmac @sbalien{define-alien-routine} @var{name} @var{result-type} &rest @var{arg-specifiers}

 
 The @code{define-alien-routine} macro is a convenience for
 automatically generating Lisp interfaces to simple foreign functions.
 
 The @code{define-alien-routine} macro is a convenience for
 automatically generating Lisp interfaces to simple foreign functions.

@@ -945,8 +915,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.