X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=510dd4ca3a64351ce68ad4c22e25e95db7680d9a;hb=1a1afe576e600f0623a4239237176b8f7c205d7a;hp=f299c197cee87f90e5045c6c1ddca6b4d89198c1;hpb=0ddd686eaa4dc3e28cf3e9472c9d46360b0091cf;p=uffi.git

diff --git a/doc/ref.sgml b/doc/ref.sgml
index f299c19..510dd4c 100644
--- 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">