X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=2fbf5ddcf6d70b28e52246815abb7f60a408a30a;hb=8689e2bd1712c080698d2c864ea62245deaccbc5;hp=549a4eb80eaedfd88b5526d4e7f7b937c4bc1e01;hpb=192193db6e4fbda90a840474d4aa2e8762597927;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 549a4eb..2fbf5dd 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -62,12 +62,74 @@
Immediate Types
+
+ Overview
+
+ Immediate types have a single value, these include
+ characters, numbers, and pointers. They are all symbols in
+ the keyword package.
+
+
+
+ :byte - Unsigned 8-bit
+
+
+ :char - Signed 8-bits
+
+
+ :unsigned-char - Unsigned 8-bits
+
+
+ :short - Signed 16-bits
+
+
+ :unsigned-short - Unsigned 16-bits
+
+
+ :int - Signed 32-bits
+
+
+ :unsigned-int - Unsigned 32-bits
+
+
+ :long - Signed 32-bits
+
+
+ :unsigned-long - Unsigned 32-bits
+
+
+ :single-float - 32-bit floating point
+
+
+ :double-float - 64-bit floating point
+
+
+
+
+ :cstring
+
+ - A null-terminated string used for passing and returning with a function.
+
+
+
+
+
+ :void
+
+ - An absence of a value. Used in generic pointers and in
+ return types from functions.
+
+
+ * - Used to declare a pointer to an object
+
+
+
def-constant
This is a thin wrapper around
- defconstant. It also exports the symbol
- from the package.
+ defconstant. It evaluates at
+ compile-time and exports the symbol from the package.
@@ -75,6 +137,16 @@
This is the main function for creating new types.
+
+ Examples
+
+
+(def-type my-generic-pointer (* :void))
+(def-type a-double-float :double-float)
+(def-type char-ptr (* :char))
+
+
+
null-char-p
@@ -96,8 +168,18 @@
def-struct
- Declares a structure.
+ Declares a structure. A special type is available as a slot in the field. It is
+ a pointer that points to an instance of the parent structure. It's type is
+ :pointer-self.
+
+ Examples
+
+
+(def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
+
+
+
get-slot-value
@@ -131,7 +213,7 @@
allocate-foreign-object
- Allocates an instance of a foreign object.
+ Allocates an instance of a foreign object. It returns a pointer to the object.
@@ -165,9 +247,9 @@
- +null-c-string-ptr+
+ +null-cstring-pointer+
- A constant returning a &null; character pointer;
+ A constant &null; character pointer.
@@ -175,31 +257,42 @@
Strings
- convert-from-c-string
+ Overview
+
+ &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.
+
+
+
+ convert-from-cstring
- Converts a Lisp string to a c-string.
+ Converts a Lisp string to a cstring.
- convert-to-c-string
+ convert-to-cstring
Converts a Lisp string to a
- c-string. These
- c-string's should be freed with
- free-c-string.
+ cstring. These
+ cstring's should be freed with
+ free-cstring.
- free-c-string
+ free-cstring
Frees any memory possibly allocated by
- convert-to-c-string.
+ convert-to-cstring.
- with-c-string
+ with-cstring
- Binds a lexical variable to a newly allocated c-string. Automatically frees c-string.
+ Binds a lexical variable to a newly allocated cstring. Automatically frees cstring.
@@ -226,11 +319,11 @@
- Routine
+ Functions
- def-routine
+ def-function
- This macro generates a &c; routine definition.
+ This macro generates a &c; function definition.