[Sbcl-commits] CVS: sbcl/doc/manual ffi.texinfo,1.13,1.14

[Juho S. <js...@us...>]

Update of /cvsroot/sbcl/sbcl/doc/manual
In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv28751/doc/manual

Modified Files:
	ffi.texinfo 
Log Message:
0.9.16.17:
	Support for external formats in SB-ALIEN. The C-STRING alien-type
        specifier now accepts :EXTERNAL-FORMAT and :ELEMENT-TYPE parameters.
        This is a slightly incompatible change: to get the behaviour of 
        the old C-STRING alien-type, use (C-STRING :EXTERNAL-FORMAT :ASCII
        :ELEMENT-TYPE BASE-CHAR).

        Thanks to Yaroslav Kavenchuk for doing most of the work on this.
        
        * Also add support for non-ascii pathnames
        * Add some recent CONTRIBUTORS
        * Update INSTALL
        * Add argument quote/space escaping to RUN-PROGRAM on win32


Index: ffi.texinfo
===================================================================
RCS file: /cvsroot/sbcl/sbcl/doc/manual/ffi.texinfo,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -d -r1.13 -r1.14
--- ffi.texinfo	21 Dec 2005 13:00:49 -0000	1.13
+++ ffi.texinfo	6 Sep 2006 20:27:10 -0000	1.14
@@ -283,15 +283,37 @@
 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