uffi/doc html.tar.gz,1.13,1.14 ref.sgml,1.32,1.33 uffi.pdf,1.17,1.18

Update of /pubcvs/uffi/doc
In directory boa.b9.com:/tmp/cvs-serv27766/doc

Modified Files:
	html.tar.gz ref.sgml uffi.pdf 
Log Message:
new deb pkg


Index: html.tar.gz
===================================================================
RCS file: /pubcvs/uffi/doc/html.tar.gz,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
Binary files /tmp/cvs5Xhim6 and /tmp/cvsk2yhs2 differ

Index: ref.sgml
===================================================================
RCS file: /pubcvs/uffi/doc/ref.sgml,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -d -r1.32 -r1.33
*** ref.sgml	22 Nov 2002 01:33:18 -0000	1.32
--- ref.sgml	23 Nov 2002 18:03:30 -0000	1.33
***************
*** 1499,1517 ****
  	  &uffi; has functions to two types of
  <varname>C</varname>-compatible
! 	  strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
  
! cstrings are used as parameters to and from functions. An
! implementation, such as CMUCL and Lispworks, a cstring may not be a
! foreign type but rather the Lisp string itself while on other
! platforms a cstring is a newly allocated foreign vector for storing
! characters. Thus, it is not possible to portably
! <emphasis>allocate</emphasis> a cstring. 
  </para>
! <para>
! In contrast, foreign strings
! are always a foreign vector of characters which have a memory
! allocated to hold them. Because of this, if you need to allocate memory to
! hold the return value of a string, use a foreign string and not a cstring.
! 	</para>
  </partintro>
  
--- 1499,1547 ----
  	  &uffi; has functions to two types of
  <varname>C</varname>-compatible
! 	  strings: <emphasis>cstring</emphasis> and
! <emphasis>foreign</emphasis> strings.
  
! cstrings are used <emphasis>only</emphasis> as parameters to and from
! functions. In some implementations a cstring is not a foreign type but
! rather the Lisp string itself. On other platforms a cstring is a newly
! allocated foreign vector for storing characters. The following is an
! example of using cstrings to both send and return a value.  
  </para>
! 
! <programlisting>
! (uffi:def-function ("getenv" c-getenv) 
!     ((name :cstring))
!   :returning :cstring)
! 
! (defun my-getenv (key)
!   "Returns an environment variable, or NIL if it does not exist"
!   (check-type key string)
!   (uffi:with-cstring (key-native key)
!     (uffi:convert-from-cstring (c-getenv key-native))))
! </programlisting>
! 
! <para> In contrast, foreign strings are always a foreign vector of
! characters which have memory allocated. Thus, if you need to allocate
! memory to hold the return value of a string, you must use a foreign
! string and not a cstring.  The following is an example of using a foreign
! string for a return value.  </para>
! 
! <programlisting>
! (uffi:def-function ("gethostname" c-gethostname)
!     ((name (* :unsigned-char))
!      (len :int))
!   :returning :int)
! 
! (defun gethostname ()
!   "Returns the hostname"
!   (let* ((name (uffi:allocate-foreign-string 256))
!          (result-code (c-gethostname name 256))
!          (hostname (when (zerop result-code)
!                      (uffi:convert-from-foreign-string name))))
!     (uffi:free-foreign-object name)
!     (unless (zerop result-code)
!       (error "gethostname() failed."))))
! </programlisting>
! 
  </partintro>
  
***************
*** 1656,1660 ****
  	<para>
  	  Frees any memory possibly allocated by
! 	  <function>convert-to-cstring</function>.
  	</para>
        </refsect1>
--- 1686,1690 ----
  	<para>
  	  Frees any memory possibly allocated by
! 	  <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
  	</para>
        </refsect1>

Index: uffi.pdf
===================================================================
RCS file: /pubcvs/uffi/doc/uffi.pdf,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
Binary files /tmp/cvsrYmMl7 and /tmp/cvsS9Qst8 differ