%eclent; ]> &UFFI; has functions to two types of C-compatible strings: cstring and foreign strings. cstrings are used only 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. (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)))) 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. (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 does not yet provide a universal way to free ;; memory allocated by C's malloc. At this point, a program ;; needs to call C's free function to free such memory. (unless (zerop result-code) (error "gethostname() failed.")))) 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. (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))) convert-from-cstring Converts a cstring to a Lisp string. Macro convert-from-cstring cstring => string cstring A cstring. string A Lisp string. Converts a Lisp string to a cstring. This is most often used when processing the results of a foreign function that returns a cstring. None. None. None. convert-to-cstring Converts a Lisp string to a cstring. Macro convert-to-cstring string => cstring string A Lisp string. cstring A cstring. Converts a Lisp string to a cstring. The cstring should be freed with free-cstring. On some implementations, this function allocates memory. None. None. free-cstring Free memory used by cstring. Macro free-cstring cstring cstring A cstring. Frees any memory possibly allocated by convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. None. None. None. with-cstring Binds a newly created cstring. Macro with-cstring (cstring string) {body} cstring A symbol naming the cstring to be created. string A Lisp string that will be translated to a cstring. body The body of where the cstring will be bound. Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. (def-function ("getenv" c-getenv) ((name :cstring)) :returning :cstring) (defun getenv (key) "Returns an environment variable, or NIL if it does not exist" (check-type key string) (with-cstring (key-cstring key) (convert-from-cstring (c-getenv key-cstring)))) None. None. None. convert-from-foreign-string Converts a foreign string into a Lisp string. Macro convert-from-foreign-string foreign-string &key length null-terminated-p => string foreign-string A foreign string. length The length of the foreign string to convert. The default is the length of the string until a &NULL; character is reached. null-terminated-p A boolean flag with a default value of &t; When true, the string is converted until the first &NULL; character is reached. string A Lisp string. Returns a Lisp string from a foreign string. Can translated ASCII and binary strings. None. None. None. convert-to-foreign-string Converts a Lisp string to a foreign string. Macro convert-to-foreign-string string => foreign-string string A Lisp string. foreign-string A foreign string. Converts a Lisp string to a foreign string. Memory should be freed with free-foreign-object. None. None. None. allocate-foreign-string Allocates space for a foreign string. allocate-foreign-string size &key unsigned => foreign-string size The size of the space to be allocated in bytes. unsigned A boolean flag with a default value of &t;. When true, marks the pointer as an :unsigned-char. foreign-string A foreign string which has undefined contents. Allocates space for a foreign string. Memory should be freed with free-foreign-object. None. None. None.