X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fref.sgml;h=6b794780a597b65a281d9797d9656b44053be9bc;hb=5d0f4d69b681b5dc15ac423442de2596da9e36d9;hp=5b783d3482ad5661f729cb1773c835b417f006bd;hpb=bc5968d54cee0416db7db9ee2c7295489170bccf;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 5b783d3..6b79478 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,26 +319,97 @@
- Routine
+ Functions
def-function
- This macro generates a &c; routine definition.
+ This macro generates a &c; function definition.
Libraries
-
- load-foreign-library
-
- This function loads foreign libraries. It has checks to
- ensure that a library is loaded only once during a session.
+
+
+ load-foreign-library
+ Loads a foreign library.
+
+ Function
+
+
+ Syntax
+
+ load-foreign-library filename module supporting-libraries => success
+
+
+
+ Arguments and Values
+
+
+ filename
+
+ A string or pathname specifying the library location
+in the filesystem.
+
+
+
+
+ module
+
+ A string designating the name of the module to apply
+to functions in this library. (Required for Lispworks)
+
+
+
+
+ supporting-libraries
+
+ A list of strings naming the libraries required to
+link the foreign library. (Required by CMUCL)
+
+
+
+
+ success
+
+ A boolean flag, &t; if the library was able to be
+loaded successfully or if the library has been previously loaded,
+otherwise &nil;.
+
+
+
+
+
+
+ Description
+ Loads a foreign library. Applies a module name to functions
+within the library. Ensures that a library is only loaded once during
+a session.
-
-
-
+
+
+ Examples
+
+ (load-foreign-library #p"/usr/lib/libmysqlclient.so" "mysql" '("c"))
+ => T
+
+
+
+ Side Effects
+ Loads the foreign code into the Lisp system.
+
+
+
+ Affected by
+ Ability to load the file.
+
+
+ Exceptional Situations
+ None.
+
+
+