1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <reference id="strings">
11 <title>Overview</title>
13 &uffi; has functions to two types of <varname>C</varname>-compatible
14 strings: <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis>
15 strings. cstrings are used <emphasis>only</emphasis> as parameters to
16 and from functions. In some implementations a cstring is not a foreign
17 type but rather the Lisp string itself. On other platforms a cstring
18 is a newly allocated foreign vector for storing characters. The
19 following is an example of using cstrings to both send and return a
24 (uffi:def-function ("getenv" c-getenv)
28 (defun my-getenv (key)
29 "Returns an environment variable, or NIL if it does not exist"
30 (check-type key string)
31 (uffi:with-cstring (key-native key)
32 (uffi:convert-from-cstring (c-getenv key-native))))
36 In contrast, foreign strings are always a foreign vector of
37 characters which have memory allocated. Thus, if you need to
38 allocate memory to hold the return value of a string, you must
39 use a foreign string and not a cstring. The following is an
40 example of using a foreign string for a return value.
44 (uffi:def-function ("gethostname" c-gethostname)
45 ((name (* :unsigned-char))
50 "Returns the hostname"
51 (let* ((name (uffi:allocate-foreign-string 256))
52 (result-code (c-gethostname name 256))
53 (hostname (when (zerop result-code)
54 (uffi:convert-from-foreign-string name))))
55 ;; UFFI does not yet provide a universal way to free
56 ;; memory allocated by C's malloc. At this point, a program
57 ;; needs to call C's free function to free such memory.
58 (unless (zerop result-code)
59 (error "gethostname() failed."))))
63 Foreign functions that return pointers to freshly allocated
64 strings should in general not return cstrings, but foreign
65 strings. (There is no portable way to release such cstrings from
66 Lisp.) The following is an example of handling such a function.
70 (uffi:def-function ("readline" c-readline)
74 (defun readline (prompt)
75 "Reads a string from console with line-editing."
76 (with-cstring (c-prompt prompt)
77 (let* ((c-str (c-readline c-prompt))
78 (str (convert-from-foreign-string c-str)))
79 (uffi:free-foreign-object c-str)
85 <refentry id="convert-from-cstring">
87 <refname>convert-from-cstring</refname>
88 <refpurpose>Converts a cstring to a Lisp string.</refpurpose>
89 <refclass>Macro</refclass>
94 <function>convert-from-cstring</function>
95 <replaceable>cstring</replaceable>
97 <returnvalue>string</returnvalue>
101 <title>Arguments and Values</title>
104 <term><parameter>cstring</parameter></term>
111 <term><returnvalue>string</returnvalue></term>
120 <title>Description</title>
122 Converts a Lisp string to a <constant>cstring</constant>. This is
123 most often used when processing the results of a foreign function
124 that returns a cstring.
128 <title>Side Effects</title>
132 <title>Affected by</title>
136 <title>Exceptional Situations</title>
142 <refentry id="convert-to-cstring">
144 <refname>convert-to-cstring</refname>
145 <refpurpose>Converts a Lisp string to a cstring.</refpurpose>
146 <refclass>Macro</refclass>
149 <title>Syntax</title>
151 <function>convert-to-cstring</function>
152 <replaceable>string</replaceable>
154 <returnvalue>cstring</returnvalue>
158 <title>Arguments and Values</title>
161 <term><parameter>string</parameter></term>
168 <term><returnvalue>cstring</returnvalue></term>
177 <title>Description</title>
179 Converts a Lisp string to a <varname>cstring</varname>. The
180 <varname>cstring</varname> should be freed with
181 <function>free-cstring</function>.
185 <title>Side Effects</title>
186 <para>On some implementations, this function allocates memory.</para>
189 <title>Affected by</title>
193 <title>Exceptional Situations</title>
199 <refentry id="free-cstring">
201 <refname>free-cstring</refname>
202 <refpurpose>Free memory used by cstring.
204 <refclass>Macro</refclass>
207 <title>Syntax</title>
209 <function>free-cstring</function> <replaceable>cstring</replaceable>
213 <title>Arguments and Values</title>
216 <term><parameter>cstring</parameter></term>
225 <title>Description</title>
227 Frees any memory possibly allocated by
228 <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
232 <title>Side Effects</title>
236 <title>Affected by</title>
240 <title>Exceptional Situations</title>
246 <refentry id="with-cstring">
248 <refname>with-cstring</refname>
249 <refpurpose>Binds a newly created cstring.</refpurpose>
250 <refclass>Macro</refclass>
253 <title>Syntax</title>
255 <function>with-cstring</function>
256 <replaceable>(cstring string) {body}</replaceable>
260 <title>Arguments and Values</title>
263 <term><parameter>cstring</parameter></term>
265 <para>A symbol naming the cstring to be created.
270 <term><parameter>string</parameter></term>
272 <para>A Lisp string that will be translated to a cstring.
277 <term><parameter>body</parameter></term>
279 <para>The body of where the cstring will be bound.
286 <title>Description</title>
288 Binds a symbol to a cstring created from conversion of a
289 string. Automatically frees the <varname>cstring</varname>.
293 <title>Examples</title>
296 (def-function ("getenv" c-getenv)
301 "Returns an environment variable, or NIL if it does not exist"
302 (check-type key string)
303 (with-cstring (key-cstring key)
304 (convert-from-cstring (c-getenv key-cstring))))
309 <title>Side Effects</title>
313 <title>Affected by</title>
317 <title>Exceptional Situations</title>
323 <refentry id="convert-from-foreign-string">
325 <refname>convert-from-foreign-string</refname>
326 <refpurpose>Converts a foreign string into a Lisp string.</refpurpose>
327 <refclass>Macro</refclass>
330 <title>Syntax</title>
332 <function>convert-from-foreign-string</function>
333 <replaceable>foreign-string &key length null-terminated-p</replaceable>
335 <returnvalue>string</returnvalue>
339 <title>Arguments and Values</title>
342 <term><parameter>foreign-string</parameter></term>
344 <para>A foreign string.
349 <term><parameter>length</parameter></term>
351 <para>The length of the foreign string to convert. The
352 default is the length of the string until a &null;
353 character is reached.
358 <term><parameter>null-terminated-p</parameter></term>
360 <para>A boolean flag with a default value of &t; When true,
361 the string is converted until the first &null; character is reached.
366 <term><returnvalue>string</returnvalue></term>
375 <title>Description</title>
377 Returns a Lisp string from a foreign string.
378 Can translated ASCII and binary strings.
382 <title>Side Effects</title>
386 <title>Affected by</title>
390 <title>Exceptional Situations</title>
396 <refentry id="convert-to-foreign-string">
398 <refname>convert-to-foreign-string</refname>
399 <refpurpose>Converts a Lisp string to a foreign string.
401 <refclass>Macro</refclass>
404 <title>Syntax</title>
406 <function>convert-to-foreign-string</function>
407 <replaceable>string</replaceable> =>
408 <returnvalue>foreign-string</returnvalue>
412 <title>Arguments and Values</title>
415 <term><parameter>string</parameter></term>
422 <term><returnvalue>foreign-string</returnvalue></term>
424 <para>A foreign string.
431 <title>Description</title>
433 Converts a Lisp string to a foreign string. Memory should be
434 freed with <function>free-foreign-object</function>.
438 <title>Side Effects</title>
442 <title>Affected by</title>
446 <title>Exceptional Situations</title>
451 <refentry id="allocate-foreign-string">
453 <refname>allocate-foreign-string</refname>
454 <refpurpose>Allocates space for a foreign string.
456 <refclass>Macro</refclass>
459 <title>Syntax</title>
461 <function>allocate-foreign-string</function> <replaceable>size
462 &key unsigned</replaceable> =>
463 <returnvalue>foreign-string</returnvalue>
467 <title>Arguments and Values</title>
470 <term><parameter>size</parameter></term>
472 <para>The size of the space to be allocated in bytes.
477 <term><parameter>unsigned</parameter></term>
479 <para>A boolean flag with a default value of &t;. When true,
480 marks the pointer as an <constant>:unsigned-char</constant>.
485 <term><returnvalue>foreign-string</returnvalue></term>
487 <para>A foreign string which has undefined contents.
494 <title>Description</title>
496 Allocates space for a foreign string. Memory should
497 be freed with <function>free-foreign-object</function>.
501 <title>Side Effects</title>
505 <title>Affected by</title>
509 <title>Exceptional Situations</title>