X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=2fbf5ddcf6d70b28e52246815abb7f60a408a30a;hb=8689e2bd1712c080698d2c864ea62245deaccbc5;hp=a0d77f11323fbdd10c7ad682704588ad9bb5998e;hpb=d088e362ddd9bdd99c2d1815ab87c5328cdc92a3;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index a0d77f1..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,15 +247,26 @@
- +null-cstring-ptr+
+ +null-cstring-pointer+
- A constant returning a &null; character pointer;
+ A constant &null; character pointer.
Strings
+
+ 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
@@ -226,11 +319,11 @@
- Routine
+ Functions
def-function
- This macro generates a &c; routine definition.
+ This macro generates a &c; function definition.