X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=aaf1feac499abe4fde3a6c841017de27e7a7328e;hb=bf5c7e7c36474375604bcbcedea8794a68dd1784;hp=2fbf5ddcf6d70b28e52246815abb7f60a408a30a;hpb=8689e2bd1712c080698d2c864ea62245deaccbc5;p=uffi.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 2fbf5dd..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,25 +314,166 @@ 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. + + 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" + :module "mysql" + :supporting-libraries '("c")) + => T + + + + Side Effects + Loads the foreign code into the Lisp system. + + + + Affected by + Ability to load the file. + + + Exceptional Situations + None. + + +