fix typo in FFI chapter

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

diff --git a/doc/manual/ffi.texinfo b/doc/manual/ffi.texinfo
index 5f365d9..0c4eb49 100644 (file)
--- a/doc/manual/ffi.texinfo
+++ b/doc/manual/ffi.texinfo
@@ -1,5 +1,9 @@
+@node  Foreign Function Interface
+@comment  node-name,  next,  previous,  up
+@chapter Foreign Function Interface
+

 This chapter describes SBCL's interface to C programs and
 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.)
 

@@ -20,7 +24,7 @@ notably in the name of the @code{SB-ALIEN} package.
 * Operations On Foreign Values::  
 * Foreign Variables::           
 * Foreign Data Structure Examples::  
 * Operations On Foreign Values::  
 * Foreign Variables::           
 * Foreign Data Structure Examples::  

-* Loading Unix Object Files::   
+* Loading Shared Object Files::  

 * Foreign Function Calls::      
 * Step-By-Step Example of the Foreign Function Interface::  
 @end menu
 * Foreign Function Calls::      
 * Step-By-Step Example of the Foreign Function Interface::  
 @end menu

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

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

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

@@ -212,9 +217,9 @@ determine which field is active from context.
 @item
 The foreign type specifier @code{(sb-alien:enum @var{name} &rest
 @var{specs})} describes an enumeration type that maps between integer
 @item
 The foreign type specifier @code{(sb-alien:enum @var{name} &rest
 @var{specs})} describes an enumeration type that maps between integer

-values and keywords. If @var{name} is @code{nil}, then the type is
+values and symbols. If @var{name} is @code{nil}, then the type is

 anonymous.  Each element of the @var{specs} list is either a Lisp
 anonymous.  Each element of the @var{specs} list is either a Lisp

-keyword, or a list @code{(@var{keyword} @var{value})}.  @var{value} is
+symbol, or a list @code{(@var{symbol} @var{value})}.  @var{value} is

 an integer. If @var{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).
 an integer. If @var{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).

@@ -277,13 +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
+@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{(* 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.
+@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

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

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

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

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

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

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

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

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

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

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

@@ -707,33 +683,16 @@ which can be manipulated in Lisp like this:
 (setq my-struct (slot my-struct 'n))
 @end lisp
 
 (setq my-struct (slot my-struct 'n))
 @end lisp
 

-@node  Loading Unix Object Files
+@node  Loading Shared Object Files

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

-@section Loading Unix Object Files
+@section Loading Shared Object Files

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

-The @code{sb-alien:load-shared-object} loads a single object file into
-the currently running Lisp. The external symbols defining routines and
-variables are made available for future external references (e.g. by
-@code{extern-alien}). Forward references to foreign symbols aren't
-supported: @code{load-shared-object} must be run before any of the
-defined symbols are referenced.
-
-@quotation
-Note: As of SBCL 0.7.5, all foreign code (code loaded with
-@code{load-shared-object}) is lost when a Lisp
-core is saved with @code{sb-ext:save-lisp-and-die}, and no attempt is
-made to restore it when the core is loaded. Historically this has been
-an annoyance both for SBCL users and for CMUCL users.  It's hard to
-solve this problem completely cleanly, but some generally-reliable
-partial solution might be useful. Once someone in either camp gets
-sufficiently annoyed to create it, SBCL is likely to adopt some
-mechanism for automatically restoring foreign code when a saved core
-is loaded.
-@end quotation
+@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
 
 @node  Foreign Function Calls
 @comment  node-name,  next,  previous,  up

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

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

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

@@ -1134,7 +1090,7 @@ struct c_struct *c_function (i, s, r, a)
   printf("s = %s\n", s);
   printf("r->x = %d\n", r->x);
   printf("r->s = %s\n", r->s);
   printf("s = %s\n", s);
   printf("r->x = %d\n", r->x);
   printf("r->s = %s\n", r->s);

-  for (j = 0; j &lt; 10; j++) printf("a[%d] = %d.\n", j, a[j]);
+  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";
   r2 = (struct c_struct *) malloc (sizeof(struct c_struct));
   r2->x = i + 5;
   r2->s = "a C string";

@@ -1197,16 +1153,15 @@ 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.)
 @samp{(compile-file "test.lisp")}
 
 Within Lisp, load the foreign object file to define the necessary
 
 Within Lisp, compile the Lisp file. (This step can be done
 separately. You don't have to recompile every time.)
 @samp{(compile-file "test.lisp")}
 
 Within Lisp, load the foreign object file to define the necessary

-symbols: @samp{(load-shared-object "test.so")}.  This must be done
-before loading any code that refers to these symbols.
+symbols: @samp{(load-shared-object "test.so")}. 

 
 Now you can load the compiled Lisp (``fasl'') file into Lisp:
 @samp{(load "test.fasl")}
 
 Now you can load the compiled Lisp (``fasl'') file into Lisp:
 @samp{(load "test.fasl")}