X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fref.sgml;h=39ae02ebaf9a920fceb1b76cef1a1671bd0f70fb;hb=005eb1c1210634a27fbc973d84004b5622456fc5;hp=714d8e99ca665e0f9a6500129b380dad5412ae0d;hpb=1796f8c038481234982c983cb0ee611c3ffac4c6;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 714d8e9..39ae02e 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -96,8 +96,12 @@ dereferenced :char pointer returns an character.
pointer returns an character.
- :byte - Unsigned 8-bits. A
+ :byte - Signed 8-bits. A
dereferenced :byte pointer returns an integer.
+
+
+ :unsigned-byte - Unsigned 8-bits. A
+dereferenced :unsigned-byte pointer returns an integer.
:short - Signed 16-bits.
@@ -315,7 +319,7 @@ abstracts the difference in implementations where some return a
Examples
-(def-array ca :char)
+(def-array-pointer ca :unsigned-char)
(let ((fs (convert-to-foreign-string "ab")))
(values (null-char-p (deref-array fs 'ca 0))
(null-char-p (deref-array fs 'ca 2))))
@@ -640,17 +644,17 @@ structure. It's type is :pointer-self.
-
+
- def-array
- Defines a foreign array type.
+ def-array-pointer
+ Defines a pointer to a array of type.
Macro
Syntax
- def-array name type
+ def-array-pointer name type
@@ -675,13 +679,13 @@ structure. It's type is :pointer-self.
Description
- Defines a foreign array type.
+ Defines a type tat is a pointer to an array of type.
Examples
-(def-array byte-array :unsigned-char)
+(def-array-pointer byte-array-pointer :unsigned-char)
@@ -877,15 +881,15 @@ can be freed.
type
- A unevaluated type of foreign object to allocate.
+ The type of foreign object to allocate. This parameter is evaluated.
size
- An optional size parameter. If specified, allocates and returns an
-array of type that is size members long.
+ An optional size parameter that is evaluated. If specified, allocates and returns an
+array of type that is size members long. This parameter is evaluated.
@@ -908,7 +912,7 @@ array of type that is size members
Examples
(def-struct ab (a :int) (b :double))
-(allocate-foreign-object ab)
+(allocate-foreign-object 'ab)
=> #<ptr>
@@ -973,6 +977,134 @@ array of type that is size members
+
+
+ with-foreign-object
+ Wraps the allocation of a foreign object around a body of code.
+
+ Macro
+
+
+ Syntax
+
+ with-foreign-object (var type) &body body => form-return
+
+
+
+ Arguments and Values
+
+
+ var
+
+ The variable name to bind.
+
+
+
+
+ type
+
+ The type of foreign object to allocate. This parameter is evaluated.
+
+
+
+
+ form-return
+
+ The result of evaluating the body.
+
+
+
+
+
+
+ Description
+
+This function wraps the allocation, binding, and destruction of a foreign object.
+On &cmucl; and
+&lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
+much better with static allocation.
+
+
+
+ Examples
+
+(defun gethostname2 ()
+ "Returns the hostname"
+ (uffi:with-foreign-object (name '(:array :unsigned-char 256))
+ (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
+ (uffi:convert-from-foreign-string name)
+ (error "gethostname() failed."))))
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
+
+
+ size-of-foreign-type
+ Returns the number of data bytes used by a foreign object type.
+
+ Macro
+
+
+ Syntax
+
+ size-of-foreign-type ftype
+
+
+
+ Arguments and Values
+
+
+ ftype
+
+ A foreign type specifier. This parameter is evaluated.
+
+
+
+
+
+
+ Description
+
+ Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead.
+
+
+
+ Examples
+
+
+(size-of-foreign-object :unsigned-byte)
+=> 1
+(size-of-foreign-object 'my-100-byte-vector-type)
+=> 100
+
+
+
+
+ Side Effects
+ None.
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+
pointer-address
@@ -1101,7 +1233,7 @@ array of type that is size members
ensure-char-character
- Ensures that a dereferenced :char pointer is
+ Ensures that a dereferenced :char pointer is
a character.
Macro
@@ -1169,7 +1301,7 @@ integer.
ensure-char-integer
- Ensures that a dereferenced :char pointer is
+ Ensures that a dereferenced :char pointer is
an integer.
Macro
@@ -1363,12 +1495,23 @@ if a cstring returned by a function is &null;.
Overview
- &uffi; has functions to two types of C-compatible
+
+ &uffi; has functions to two types of
+C-compatible
strings, cstring and foreign strings.
-cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
-may not convert these to a foreign type for efficiency sake. Thus, it is not
-possible to "allocate" a cstring. In contrast, foreign strings
-always need to have memory for them.
+
+cstrings are used as parameters to and from functions. An
+implementation, such as CMUCL and Lispworks, a cstring may not be a
+foreign type but rather the Lisp string itself while on other
+platforms a cstring is a newly allocated foreign vector for storing
+characters. Thus, it is not possible to portably
+allocate a cstring.
+
+
+In contrast, foreign strings
+are always a foreign vector of characters which have a memory
+allocated to hold them. Because of this, if you need to allocate memory to
+hold the return value of a string, use a foreign string and not a cstring.
@@ -1470,7 +1613,7 @@ that returns a cstring.
Side Effects
- None.
+ On some implementations, this function allocates memory.
Affected by
@@ -1572,7 +1715,7 @@ that returns a cstring.
Description
- Binds a lexical variable to a newly allocated cstring. Automatically frees cstring.
+ Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring.
@@ -1955,6 +2098,91 @@ a session.
+
+
+ find-foreign-library
+ Finds a foreign library file.
+
+ Function
+
+
+ Syntax
+
+ find-foreign-library names directories & drive-letters types => path
+
+
+
+ Arguments and Values
+
+
+ names
+
+ A string or list of strings containing the base name of the library file.
+
+
+
+
+ directories
+
+ A string or list of strings containing the directory the library file.
+
+
+
+
+ drive-letters
+
+ A string or list of strings containing the drive letters for the library file.
+
+
+
+
+ types
+
+ A string or list of strings containing the file type of the library file. Default
+is &nil;. If &nil;, will use a default type based on the currently running implementation.
+
+
+
+
+ path
+
+ A path containing the path found, or &nil; if the library file was not found.
+
+
+
+
+
+
+ Description
+ Finds a foreign library by searching through a number of possible locations. Returns
+the path of the first found file.
+
+
+
+ Examples
+
+(find-foreign-library '("libmysqlclient" "libmysql")
+ '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
+ :types '("so" "dll")
+ :drive-letters '("C" "D" "E"))
+=> #P"D:\\mysql\\lib\\opt\\libmysql.dll"
+
+
+
+ Side Effects
+ None.
+
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
+