fix typo in FFI chapter

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

diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index b65b2bc..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

@@ -283,11 +282,14 @@ 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 &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}.
+@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
+@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.
 
 External format conversion is automatically done when Lisp strings are
 passed to foreign code, or when foreign strings are passed to Lisp code.

@@ -339,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
 

@@ -368,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

@@ -381,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} @var{slot-name}
-@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

@@ -404,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

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

-@end defun
+@end defmac

 
 

-@defun sb-alien:alien-sap @var{foreign-value}
-@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.

@@ -483,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
+@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.

 
 

-@end defmac
-
-@defun sb-alien:free-alien @var{foreign-value}
-@findex free-alien
-
-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

@@ -557,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

@@ -616,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}.

@@ -643,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

@@ -654,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

@@ -746,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

@@ -777,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

@@ -831,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.