X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=aaf1feac499abe4fde3a6c841017de27e7a7328e;hb=bf5c7e7c36474375604bcbcedea8794a68dd1784;hp=6b794780a597b65a281d9797d9656b44053be9bc;hpb=5d0f4d69b681b5dc15ac423442de2596da9e36d9;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 6b79478..aaf1fea 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -27,52 +27,31 @@
-
- uffi-declare
-
- This is used wherever a declare
- expression can be placed. For example:
-
-
-
-(let ((my-structure (uffi:allocate-foreign-object 'a-struct)))
- (uffi:uffi-declare a-struct my-structure))
-
-
-
-
-
- slot-type
+
+ def-type
- This is used inside of defclass and
- defstruct expressions to set the type
- for a field. Because the type identifier is not evaluated in
- &cl;, the expression must be backquoted for effect. For
- example:
-
+ This is used wherever a &cl; deftype
+ expression can be placed. Used to declare types to
+the compiler for optimization. Currently, on &cmucl; takes advantage
+of this.
-(eval
- `(defclass a-class ()
- ((char-ptr :type ,(uffi:slot-type (* :char))))))
+(uffi:def-type my-struct-def my-struct-foreign-type)
- Immediate Types
+ Primitive Types
Overview
- Immediate types have a single value, these include
+ Primitive 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
@@ -98,26 +77,19 @@
:unsigned-long - Unsigned 32-bits
- :single-float - 32-bit floating point
+ :float - 32-bit floating point
- :double-float - 64-bit floating point
+ :double - 64-bit floating point
-
-
- :cstring
-
- - A null-terminated string used for passing and returning with a function.
-
+ :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.
+ :void -
+The absence of a value. Used in generic pointers and in return types from functions.
* - Used to declare a pointer to an object
@@ -210,6 +182,12 @@
Objects
+
+ Overview
+
+ Objects are entities that can allocated and freed.
+
+
allocate-foreign-object
@@ -277,8 +255,8 @@ always need to have memory for them.
convert-to-cstring
Converts a Lisp string to a
- cstring. These
- cstring's should be freed with
+ cstring. The
+ cstring should be freed with
free-cstring.
@@ -294,9 +272,25 @@ always need to have memory for them.
Binds a lexical variable to a newly allocated cstring. Automatically frees cstring.
+
+ Examples
+
+
+(def-function ("getenv" c-getenv)
+ ((name :cstring))
+ :returning :cstring)
+
+(defun getenv (key)
+ "Returns an environment variable, or NIL if it does not exist"
+ (check-type key string)
+ (with-cstring (key-cstring key)
+ (convert-from-cstring (c-getenv key-cstring))))
+
+
+
- covert-from-foreign-string
+ convert-from-foreign-string
Returns a Lisp string from a foreign string. Has parameters
to handle ASCII versus binary strings.
@@ -320,12 +314,79 @@ always need to have memory for them.
Functions
-
- def-function
-
- This macro generates a &c; function definition.
+
+
+ def-function
+ Declares a function.
+
+ Macro
+
+
+ Syntax
+
+ def-function name args &key module returning
+
+
+
+ Arguments and Values
+
+
+ name
+
+ A string or list specificying the function name. If it is a string, that names the foreign function. A Lisp name is created by translating #\_ to #\- and by converting to upper-case in case-insensitive Lisp implementations. If it is a list, the first item is a string specifying the foreign function name and the second it is a symbol stating the Lisp name.
+
+
+
+
+ args
+
+ A list of argument declarations. Use &nil; to specify no arguments.
+
+
+
+
+ module
+
+ A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)
+
+
+
+ returning
+
+ A declaration specifying the result type of the
+foreign function.
+
+
+
+
+
+
+ Description
+ Declares a foreign function.
-
+
+
+ Examples
+
+(def-function "gethostname"
+ ((name :cstring)
+ (len :int))
+ :returning :int)
+
+
+
+ Side Effects
+ None.
+
+
+ Affected by
+ None.
+
+
+ Exceptional Situations
+ None.
+
+
@@ -340,7 +401,7 @@ always need to have memory for them.
Syntax
- load-foreign-library filename module supporting-libraries => success
+ load-foreign-library filename &key module supporting-libraries => success
@@ -350,7 +411,8 @@ always need to have memory for them.
filename
A string or pathname specifying the library location
-in the filesystem.
+in the filesystem. At least one implementation (&lw;) can not
+accept a logical pathname.
@@ -391,7 +453,9 @@ a session.
Examples
- (load-foreign-library #p"/usr/lib/libmysqlclient.so" "mysql" '("c"))
+ (load-foreign-library #p"/usr/lib/libmysqlclient.so"
+ :module "mysql"
+ :supporting-libraries '("c"))
=> T