X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=2935dcf7346c47a21c6a160b2c1819f54df683ad;hb=c7b9e795a73b25b3c81ecb1c8c69b8f0f944a064;hp=549a4eb80eaedfd88b5526d4e7f7b937c4bc1e01;hpb=192193db6e4fbda90a840474d4aa2e8762597927;p=uffi.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 549a4eb..2935dcf 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -61,13 +61,65 @@ - Immediate Types + Primitive Types + + Overview + + Primitive types have a single value, these include + characters, numbers, and pointers. They are all symbols in + the keyword package. + + + + :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 + + + :float - 32-bit floating point + + + :double - 64-bit floating point + + + :cstring - +A null-terminated string used for passing and returning with a function. + + + + :void - +The 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 +127,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 +158,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 @@ -128,10 +200,16 @@ Objects + + Overview + + Objects are entities that can allocated and freed. + + 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 +243,9 @@ - +null-c-string-ptr+ + +null-cstring-pointer+ - A constant returning a &null; character pointer; + A constant &null; character pointer. @@ -175,35 +253,62 @@ Strings - convert-from-c-string + Overview - Converts a Lisp string to a c-string. + &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-to-c-string + convert-from-cstring + + Converts a Lisp string to a cstring. + + + + convert-to-cstring Converts a Lisp string to a - c-string. These - c-string's should be freed with - free-c-string. + cstring. The + cstring 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. + + + 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. @@ -226,26 +331,165 @@ - Routine - - def-routine - - This macro generates a &c; routine 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. + + +