X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=2935dcf7346c47a21c6a160b2c1819f54df683ad;hb=c7b9e795a73b25b3c81ecb1c8c69b8f0f944a064;hp=6b794780a597b65a281d9797d9656b44053be9bc;hpb=5d0f4d69b681b5dc15ac423442de2596da9e36d9;p=uffi.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 6b79478..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. @@ -320,12 +332,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 +419,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 +429,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.