X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=2935dcf7346c47a21c6a160b2c1819f54df683ad;hb=c7b9e795a73b25b3c81ecb1c8c69b8f0f944a064;hp=0bc5b4762013d694097ca3a229b0a3064d8a21f8;hpb=737a3e3a8d18dd80f4cda0d93bc20a3b5677dbee;p=uffi.git
diff --git a/doc/ref.sgml b/doc/ref.sgml
index 0bc5b47..2935dcf 100644
--- a/doc/ref.sgml
+++ b/doc/ref.sgml
@@ -61,18 +61,15 @@
- 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 +95,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 +200,12 @@
Objects
+
+ Overview
+
+ Objects are entities that can allocated and freed.
+
+
allocate-foreign-object
@@ -277,8 +273,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 +290,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.
@@ -319,26 +331,165 @@ always need to have memory for them.
- Routine
-
- def-function
-
- This macro generates a &c; function definition.
-
-
+ Functions
+
+
+ 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.
+
+
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 &key module supporting-libraries => success
+
+
+
+ Arguments and Values
+
+
+ filename
+
+ A string or pathname specifying the library location
+in the filesystem. At least one implementation (&lw;) can not
+accept a logical pathname.
+
+
+
+
+ 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.
+
+
+