r4817: Auto commit for Debian build
[uffi.git] / doc / ref.sgml
index f299c197cee87f90e5045c6c1ddca6b4d89198c1..510dd4ca3a64351ce68ad4c22e25e95db7680d9a 100644 (file)
@@ -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">