r4817: Auto commit for Debian build

diff --git a/debian/changelog b/debian/changelog
index 27859e2fafc4554d2d11a01921cbeb34d5687ba9..dccfffe4a247a0ab485739c9bda10ef660056a9c 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+cl-uffi (1.2.15-1) unstable; urgency=low
+
+  * Documentation improvement by Nikodemus Siivola
+
+ -- Kevin M. Rosenberg <kmr@debian.org>  Mon,  5 May 2003 15:57:32 -0600
+
 cl-uffi (1.2.14-1) unstable; urgency=low
 
   * New upstream

diff --git a/doc/ref.sgml b/doc/ref.sgml
index f299c197cee87f90e5045c6c1ddca6b4d89198c1..510dd4ca3a64351ce68ad4c22e25e95db7680d9a 100644 (file)
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -1543,6 +1543,25 @@ string for a return value.  </para>
       (error "gethostname() failed."))))
 </programlisting>
 
+<para>  Foreign functions that return pointers to freshly allocated
+strings should in general not return cstrings, but foreign strings.
+(There is no portable way to release such cstrings from Lisp.)  The
+following is an example of handling such a function.  </para>
+
+<programlisting>
+(uffi:def-function ("readline" c-readline)
+    ((prompt :cstring))
+  :returning (* :char))
+
+(defun readline (prompt)
+  "Reads a string from console with line-editing."
+  (with-cstring (c-prompt prompt)
+      (let* ((c-str (c-readline c-prompt))
+             (str (convert-from-foreign-string c-str)))
+        (uffi:free-foreign-object c-str)
+        str)))
+</programlisting>
+
 </partintro>
 
     <refentry id="convert-from-cstring">