X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref_string.xml;h=235950a8fa1cc34ce2715a1028850d24fd86e01c;hb=HEAD;hp=60537a8b1ccc075ce4916f28f83742874b2df7b2;hpb=6be0cb84dd1fc6a0ae9410f7ccdc34ac21ae4377;p=uffi.git
diff --git a/doc/ref_string.xml b/doc/ref_string.xml
index 60537a8..235950a 100644
--- a/doc/ref_string.xml
+++ b/doc/ref_string.xml
@@ -1,47 +1,46 @@
-
+
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+
%myents;
]>
- Strings
-
-Overview
-
-
- &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.
-
-
-
+ Strings
+
+ Overview
+
+ &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)
+ ((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.
+
+ 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))
@@ -53,17 +52,21 @@ string for a return value.
(result-code (c-gethostname name 256))
(hostname (when (zerop result-code)
(uffi:convert-from-foreign-string name))))
- (uffi:free-foreign-object 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.
+
+ 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))
@@ -75,21 +78,23 @@ following is an example of handling such a function.
(str (convert-from-foreign-string c-str)))
(uffi:free-foreign-object c-str)
str)))
-
-
-
-
+
+
+
+
convert-from-cstring
- Converts a cstring to a Lisp string.
-
+ Converts a cstring to a Lisp string.
Macro
Syntax
- convert-from-cstring cstring => string
+ convert-from-cstring
+ cstring
+ =>
+ string
@@ -115,8 +120,8 @@ following is an example of handling such a function.
Description
Converts a Lisp string to a cstring. This is
-most often used when processing the results of a foreign function
-that returns a cstring.
+ most often used when processing the results of a foreign function
+ that returns a cstring.
@@ -131,161 +136,163 @@ that returns a cstring.
Exceptional Situations
None.
-
-
-
-
-
- convert-to-cstring
- Converts a Lisp string to a cstring.
-
- Macro
-
-
- Syntax
-
- convert-to-cstring string => cstring
-
-
-
- Arguments and Values
-
-
- string
-
- A Lisp string.
-
-
-
-
- cstring
-
- A cstring.
-
-
-
-
-
-
- Description
-
- Converts a Lisp string to a
- cstring. The
- cstring should be freed with
- free-cstring.
-
-
-
- Side Effects
- On some implementations, this function allocates memory.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
-
-
- free-cstring
- Free memory used by cstring.
-
- Macro
-
-
- Syntax
-
- free-cstring cstring
-
-
-
- Arguments and Values
-
-
- cstring
-
- A cstring.
-
-
-
-
-
-
- Description
-
- Frees any memory possibly allocated by
- convert-to-cstring. On some implementions, a cstring is just the Lisp string itself.
-
-
-
- Side Effects
- None.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
-
-
- with-cstring
- Binds a newly created cstring.
-
- Macro
-
-
- Syntax
-
- with-cstring (cstring string) {body}
-
-
-
- Arguments and Values
-
-
- 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.
-
-
-
-
-
-
- Description
-
- Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring.
-
-
-
- Examples
-
-
+
+
+
+
+
+ convert-to-cstring
+ Converts a Lisp string to a cstring.
+ Macro
+
+
+ Syntax
+
+ convert-to-cstring
+ string
+ =>
+ cstring
+
+
+
+ Arguments and Values
+
+
+ string
+
+ A Lisp string.
+
+
+
+
+ cstring
+
+ A cstring.
+
+
+
+
+
+
+ Description
+
+ Converts a Lisp string to a cstring. The
+ cstring should be freed with
+ free-cstring.
+
+
+
+ Side Effects
+ On some implementations, this function allocates memory.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+
+ free-cstring
+ Free memory used by cstring.
+
+ Macro
+
+
+ Syntax
+
+ free-cstring cstring
+
+
+
+ Arguments and Values
+
+
+ cstring
+
+ A cstring.
+
+
+
+
+
+
+ Description
+
+ Frees any memory possibly allocated by
+ convert-to-cstring. On some implementions, a cstring is just the Lisp string itself.
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+
+ with-cstring
+ Binds a newly created cstring.
+ Macro
+
+
+ Syntax
+
+ with-cstring
+ (cstring string) {body}
+
+
+
+ Arguments and Values
+
+
+ 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.
+
+
+
+
+
+
+ Description
+
+ Binds a symbol to a cstring created from conversion of a
+ string. Automatically frees the cstring.
+
+
+
+ Examples
+
+
(def-function ("getenv" c-getenv)
((name :cstring))
:returning :cstring)
@@ -295,209 +302,213 @@ that returns a cstring.
(check-type key string)
(with-cstring (key-cstring key)
(convert-from-cstring (c-getenv key-cstring))))
-
-
-
-
- Side Effects
- None.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
-
-
- convert-from-foreign-string
- Converts a foreign string into a Lisp string.
-
- Macro
-
-
- Syntax
-
- convert-from-foreign-string foreign-string &key length null-terminated-p => string
-
-
-
- Arguments and Values
-
-
- 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.
-
-
-
-
-
-
- Description
-
- Returns a Lisp string from a foreign string.
-Can translated ASCII and binary strings.
-
-
-
- Side Effects
- None.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
-
-
- convert-to-foreign-string
- Converts a Lisp string to a foreign string.
-
- Macro
-
-
- Syntax
-
- convert-to-foreign-string string => foreign-string
-
-
-
- Arguments and Values
-
-
- string
-
- A Lisp string.
-
-
-
-
- foreign-string
-
- A foreign string.
-
-
-
-
-
-
- Description
-
- Converts a Lisp string to a foreign string. Memory should be
- freed with free-foreign-object.
-
-
-
- Side Effects
- None.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
-
-
-
- allocate-foreign-string
- Allocates space for a foreign string.
-
- Macro
-
-
- Syntax
-
- allocate-foreign-string size &key unsigned => foreign-string
-
-
-
- Arguments and Values
-
-
- 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.
-
-
-
-
-
-
- Description
-
- Allocates space for a foreign string. Memory should
- be freed with free-foreign-object.
-
-
-
- Side Effects
- None.
-
-
- Affected by
- None.
-
-
- Exceptional Situations
- None.
-
-
-
-
+
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+
+ convert-from-foreign-string
+ Converts a foreign string into a Lisp string.
+ Macro
+
+
+ Syntax
+
+ convert-from-foreign-string
+ foreign-string &key length null-terminated-p
+ =>
+ string
+
+
+
+ Arguments and Values
+
+
+ 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.
+
+
+
+
+
+
+ Description
+
+ Returns a Lisp string from a foreign string.
+ Can translated ASCII and binary strings.
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+
+ convert-to-foreign-string
+ Converts a Lisp string to a foreign string.
+
+ Macro
+
+
+ Syntax
+
+ convert-to-foreign-string
+ string =>
+ foreign-string
+
+
+
+ Arguments and Values
+
+
+ string
+
+ A Lisp string.
+
+
+
+
+ foreign-string
+
+ A foreign string.
+
+
+
+
+
+
+ Description
+
+ Converts a Lisp string to a foreign string. Memory should be
+ freed with free-foreign-object.
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+ allocate-foreign-string
+ Allocates space for a foreign string.
+
+ Macro
+
+
+ Syntax
+
+ allocate-foreign-string size
+ &key unsigned =>
+ foreign-string
+
+
+
+ Arguments and Values
+
+
+ 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.
+
+
+
+
+
+
+ Description
+
+ Allocates space for a foreign string. Memory should
+ be freed with free-foreign-object.
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+