X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=d19c7a6ad47c35e35bbec7dd7f606724e48b28f5;hb=733ccdb62a1d595dca9dc015f390eac66a11345e;hp=252bdc53c8894657887f6150a7155758dedb99de;hpb=d5d0bfb15f7a30ac5398211708f5f5d9d4a95e04;p=uffi.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 252bdc5..d19c7a6 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -88,43 +88,57 @@ - :char - Signed 8-bits + :char - Signed 8-bits. A +dereferenced :char pointer returns an character. - :unsigned-char - Unsigned 8-bits + :unsigned-char - Unsigned 8-bits. A dereferenced :unsigned-char +pointer returns an character. - :short - Signed 16-bits + :byte - Signed 8-bits. A +dereferenced :byte pointer returns an integer. + + + :unsigned-byte - Unsigned 8-bits. A +dereferenced :unsigned-byte pointer returns an integer. + + + :short - Signed 16-bits. - :unsigned-short - Unsigned 16-bits + :unsigned-short - Unsigned 16-bits. - :int - Signed 32-bits + :int - Signed 32-bits. - :unsigned-int - Unsigned 32-bits + :unsigned-int - Unsigned 32-bits. - :long - Signed 32-bits + :long - Signed 32 or 64 bits, depending upon the platform. - :unsigned-long - Unsigned 32-bits + :unsigned-long - Unsigned 32 or 64 bits, depending upon the platform. - :float - 32-bit floating point + :float - 32-bit floating point. - :double - 64-bit floating point + :double - 64-bit floating point. :cstring - -A null-terminated string used for passing and returning with a function. +A &null; terminated string used for passing and returning characters strings with a &c; function. :void - -The absence of a value. Used in generic pointers and in return types from functions. +The absence of a value. Used to indicate that a function does not return a value. + + + :pointer-void - +Points to a generic object. * - Used to declare a pointer to an object @@ -240,7 +254,7 @@ foreign type. Examples -(def-foreign-type my-generic-pointer (* :void)) +(def-foreign-type my-generic-pointer :pointer-void) (def-foreign-type a-double-float :double-float) (def-foreign-type char-ptr (* :char)) @@ -305,7 +319,7 @@ abstracts the difference in implementations where some return a Examples -(def-array ca :char) +(def-array-pointer ca :unsigned-char) (let ((fs (convert-to-foreign-string "ab"))) (values (null-char-p (deref-array fs 'ca 0)) (null-char-p (deref-array fs 'ca 2)))) @@ -327,86 +341,20 @@ abstracts the difference in implementations where some return a None. + - - - ensure-char - Ensures value is a character. - - Macro - - - Syntax - - ensure-char obj => char - - - - Arguments and Values - - - obj - - A character or integer. - - - - - char - - A character value. - - - - - - - Description - - Enscapsulates the fact that some implementations return a character -and others return an integer when dereferencing a character pointer. - - - - Examples - - -(let ((fs (convert-to-foreign-string "a"))) - (prog1 - (ensure-char (deref-pointer fs :char)) - (free-foreign-object fs))) -=> #\a - - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - Signals an error if obj is not -an integer or character. - - - - - - Aggregate Types + + Aggregate Types Overview Aggregate types are comprised of one or more primitive types. - + - - - def-enum + + + def-enum Defines a &c; enumeration. Macro @@ -552,7 +500,7 @@ structure. It's type is :pointer-self. - def-slot-value + get-slot-value Retrieves a value from a slot of a structure. Macro @@ -696,17 +644,17 @@ structure. It's type is :pointer-self. - + - def-array - Defines a foreign array type. + def-array-pointer + Defines a pointer to a array of type. Macro Syntax - def-array name type + def-array-pointer name type @@ -731,13 +679,13 @@ structure. It's type is :pointer-self. Description - Defines a foreign array type. + Defines a type tat is a pointer to an array of type. Examples -(def-array byte-array :unsigned-char) +(def-array-pointer byte-array-pointer :unsigned-char) @@ -811,7 +759,7 @@ the array. Examples -(def-array ca :char) +(def-array-pointer ca :char) (let ((fs (convert-to-foreign-string "ab"))) (values (null-char-p (deref-array fs 'ca 0)) (null-char-p (deref-array fs 'ca 2)))) @@ -819,6 +767,14 @@ the array. &t; + + Notes + + The TYPE argument is ignored for CL implementations other than + AllegroCL. If you want to cast a pointer to another type use + WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY. + + Side Effects None. @@ -832,6 +788,75 @@ the array. None. + + + + def-union + Defines a foreign union type. + + Macro + + + Syntax + + def-union name &rest fields + + + + Arguments and Values + + + name + + A name of the new union type. + + + + + fields + + A list of fields of the union. + + + + + + + Description + + Defines a foreign union type. + + + + Examples + +(def-union test-union + (a-char :char) + (an-int :int)) + +(let ((u (allocate-foreign-object 'test-union)) + (setf (get-slot-value u 'test-union 'an-int) (+ 65 (* 66 256))) + (prog1 + (ensure-char-character (get-slot-value u 'test-union 'a-char)) + (free-foreign-object u))) +=> #\A + + + + Side Effects + Defines a new foreign type. + + + Affected by + None. + + + Exceptional Situations + None. + + + + @@ -839,7 +864,8 @@ the array. Overview - Objects are entities that can allocated and freed. + Objects are entities that can allocated, referred to by pointers, and +can be freed. @@ -854,7 +880,7 @@ the array. Syntax - allocate-foreign-object type => ptr + allocate-foreign-object type &optional size => ptr @@ -863,7 +889,15 @@ the array. type - A type of foreign object to allocate. + The type of foreign object to allocate. This parameter is evaluated. + + + + + size + + An optional size parameter that is evaluated. If specified, allocates and returns an +array of type that is size members long. This parameter is evaluated. @@ -951,33 +985,40 @@ the array. - + - pointer-address - Returns the address of a pointer. + with-foreign-object + Wraps the allocation of a foreign object around a body of code. Macro Syntax - pointer-address ptr => address + with-foreign-object (var type) &body body => form-return Arguments and Values - ptr + var - A pointer to a foreign object. + The variable name to bind. - address + type - An integer representing the pointer's address. + The type of foreign object to allocate. This parameter is evaluated. + + + + + form-return + + The result of evaluating the body. @@ -986,9 +1027,23 @@ the array. Description - Returns the address as an integer of a pointer. +This function wraps the allocation, binding, and destruction of a foreign object. +On &cmucl; and +&lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs +much better with static allocation. + + Examples + +(defun gethostname2 () + "Returns the hostname" + (uffi:with-foreign-object (name '(:array :unsigned-char 256)) + (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256)) + (uffi:convert-from-foreign-string name) + (error "gethostname() failed.")))) + + Side Effects None. @@ -1003,41 +1058,26 @@ the array. - - + - deref-pointer - Deferences a pointer. + size-of-foreign-type + Returns the number of data bytes used by a foreign object type. Macro Syntax - def-pointer ptr type => value + size-of-foreign-type ftype Arguments and Values - ptr - - A pointer to a foreign object. - - - - - type - - A foreign type of the object being pointed to. - - - - - value + ftype - The value of the object where the pointer points. + A foreign type specifier. This parameter is evaluated. @@ -1046,26 +1086,24 @@ the array. Description - Returns the object to which a pointer points. + Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead. Examples -(let ((fs (convert-to-foreign-string "a"))) - (prog1 - (ensure-char (deref-pointer fs :char)) - (free-foreign-object fs))) -=> #\a +(size-of-foreign-object :unsigned-byte) +=> 1 +(size-of-foreign-object 'my-100-byte-vector-type) +=> 100 - + Side Effects None. - - + Affected by None. @@ -1075,33 +1113,33 @@ the array. - + - make-null-pointer - Create a &null; pointer. + pointer-address + Returns the address of a pointer. Macro Syntax - make-null-pointer type => ptr + pointer-address ptr => address Arguments and Values - type + ptr - A type of object to which the pointer refers. + A pointer to a foreign object. - ptr + address - The &null; pointer of type type. + An integer representing the pointer's address. @@ -1110,7 +1148,7 @@ the array. Description - Creates a &null; pointer of a specified type. + Returns the address as an integer of a pointer. @@ -1128,17 +1166,17 @@ the array. - + - null-pointer-p - Tests a pointer for &null; value. + deref-pointer + Deferences a pointer. Macro Syntax - null-pointer-p ptr => is-null + deref-pointer ptr type => value @@ -1147,14 +1185,21 @@ the array. ptr - A foreign object pointer. + A pointer to a foreign object. - is-null + type - The boolean flag. + A foreign type of the object being pointed to. + + + + + value + + The value of the object where the pointer points. @@ -1163,9 +1208,30 @@ the array. Description - A predicate testing if a pointer is has a &null; value. + Returns the object to which a pointer points. + + + + Examples + + +(let ((intp (allocate-foreign-object :int))) + (setf (deref-pointer intp :int) 10) + (prog1 + (deref-pointer intp :int) + (free-foreign-object intp))) +=> 10 + + + Notes + + The TYPE argument is ignored for CL implementations other than + AllegroCL. If you want to cast a pointer to another type use + WITH-CAST-POINTER together with DEREF-POINTER/DEREF-ARRAY. + + Side Effects None. @@ -1180,22 +1246,465 @@ the array. - - + - +null-cstring-pointer+ - A constant &null; cstring pointer. + ensure-char-character + Ensures that a dereferenced :char pointer is +a character. - Constant + Macro + + Syntax + + ensure-char-character object => char + + + + Arguments and Values + + + object + + Either a character or a integer specifying a character code. + + + + + char + + A character. + + + + + Description - A &null; cstring pointer. This can be used for testing -if a cstring returned by a function is &null;. + Ensures that an objects obtained by dereferencing +:char and :unsigned-char +pointers are a lisp character. - + + Examples + + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char-character (deref-pointer fs :char)) + (free-foreign-object fs))) +=> #\a + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + Depending upon the implementation and what &uffi; expects, this +macro may signal an error if the object is not a character or +integer. + + + + + + ensure-char-integer + Ensures that a dereferenced :char pointer is +an integer. + + Macro + + + Syntax + + ensure-char-integer object => int + + + + Arguments and Values + + + object + + Either a character or a integer specifying a character code. + + + + + int + + An integer. + + + + + + + Description + + Ensures that an object obtained by dereferencing a +:char pointer is an integer. + + + + Examples + + +(let ((fs (convert-to-foreign-string "a"))) + (prog1 + (ensure-char-integer (deref-pointer fs :char)) + (free-foreign-object fs))) +=> 96 + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + Depending upon the implementation and what &uffi; expects, this +macro may signal an error if the object is not a character or +integer. + + + + + + make-null-pointer + Create a &null; pointer. + + Macro + + + Syntax + + make-null-pointer type => ptr + + + + Arguments and Values + + + type + + A type of object to which the pointer refers. + + + + + ptr + + The &null; pointer of type type. + + + + + + + Description + + Creates a &null; pointer of a specified type. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + null-pointer-p + Tests a pointer for &null; value. + + Macro + + + Syntax + + null-pointer-p ptr => is-null + + + + Arguments and Values + + + ptr + + A foreign object pointer. + + + + + is-null + + The boolean flag. + + + + + + + Description + + A predicate testing if a pointer is has a &null; value. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + +null-cstring-pointer+ + A constant &null; cstring pointer. + + Constant + + + Description + + A &null; cstring pointer. This can be used for testing +if a cstring returned by a function is &null;. + + + + + + + with-cast-pointer + Wraps a body of code with a pointer cast to a new type. + + Macro + + + Syntax + + with-cast-pointer (binding-name ptr type) & body body => value + + + + Arguments and Values + + + ptr + + A pointer to a foreign object. + + + + + type + + A foreign type of the object being pointed to. + + + + + value + + The value of the object where the pointer points. + + + + + + + Description + + Executes BODY with POINTER cast to be a pointer to type TYPE. If + BINDING-NAME is provided the cast pointer will be bound to this + name during the execution of BODY. If BINDING-NAME is not provided + POINTER must be a name bound to the pointer which should be + cast. This name will be bound to the cast pointer during the + execution of BODY. + + This is a no-op in AllegroCL but will wrap BODY in a LET form if + BINDING-NAME is provided. + + This macro is meant to be used in conjunction with DEREF-POINTER or + DEREF-ARRAY. In Allegro CL the "cast" will actually take place in + DEREF-POINTER or DEREF-ARRAY. + + + + Examples + +(with-foreign-object (size :int) + ;; FOO is a foreign function returning a :POINTER-VOID + (let ((memory (foo size))) + (when (mumble) + ;; at this point we know for some reason that MEMORY points + ;; to an array of unsigned bytes + (with-cast-pointer (memory :unsigned-byte) + (dotimes (i (deref-pointer size :int)) + (do-something-with + (deref-array memory '(:array :unsigned-byte) i))))))) + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + def-foreign-var + +Defines a symbol macro to access a variable in foreign code + + Macro + + + Syntax + + def-foreign-var name type module + + + + Arguments and Values + + + name + + +A string or list specificying the symbol macro's name. If it is a + string, that names the foreign variable. 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 variable name and the + second it is a symbol stating the Lisp name. + + + + + type + + A foreign type of the foreign variable. + + + + + module + + + A string specifying the module (or library) the foreign variable + resides in. (Required by Lispworks) + + + + + + + Description + +Defines a symbol macro which can be used to access (get and set) the +value of a variable in foreign code. + + + + Examples + + C code + + int baz = 3; + + typedef struct { + int x; + double y; + } foo_struct; + + foo_struct the_struct = { 42, 3.2 }; + + int foo () { + return baz; + } + + + +Lisp code + + (uffi:def-struct foo-struct + (x :int) + (y :double)) + + (uffi:def-function ("foo" foo) + () + :returning :int + :module "foo") + + (uffi:def-foreign-var ("baz" *baz*) :int "foo") + (uffi:def-foreign-var ("the_struct" *the-struct*) foo-struct "foo") + + +*baz* + => 3 + +(incf *baz*) + => 4 + +(foo) + => 4 + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + @@ -1204,13 +1713,73 @@ if a cstring returned by a function is &null;. Overview - &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. - + + &uffi; has functions to two types of +C-compatible + strings: cstring and +foreign strings. + +cstrings are used only as parameters to and from +functions. In some implementations a cstring is not a foreign type but +rather the Lisp string itself. On other platforms a cstring is a newly +allocated foreign vector for storing characters. The following is an +example of using cstrings to both send and return a value. + + + +(uffi:def-function ("getenv" c-getenv) + ((name :cstring)) + :returning :cstring) + +(defun my-getenv (key) + "Returns an environment variable, or NIL if it does not exist" + (check-type key string) + (uffi:with-cstring (key-native key) + (uffi:convert-from-cstring (c-getenv key-native)))) + + + In contrast, foreign strings are always a foreign vector of +characters which have memory allocated. Thus, if you need to allocate +memory to hold the return value of a string, you must use a foreign +string and not a cstring. The following is an example of using a foreign +string for a return value. + + +(uffi:def-function ("gethostname" c-gethostname) + ((name (* :unsigned-char)) + (len :int)) + :returning :int) + +(defun gethostname () + "Returns the hostname" + (let* ((name (uffi:allocate-foreign-string 256)) + (result-code (c-gethostname name 256)) + (hostname (when (zerop result-code) + (uffi:convert-from-foreign-string name)))) + (uffi:free-foreign-object name) + (unless (zerop result-code) + (error "gethostname() failed.")))) + + + Foreign functions that return pointers to freshly allocated +strings should in general not return cstrings, but foreign strings. +(There is no portable way to release such cstrings from Lisp.) The +following is an example of handling such a function. + + +(uffi:def-function ("readline" c-readline) + ((prompt :cstring)) + :returning (* :char)) + +(defun readline (prompt) + "Reads a string from console with line-editing." + (with-cstring (c-prompt prompt) + (let* ((c-str (c-readline c-prompt)) + (str (convert-from-foreign-string c-str))) + (uffi:free-foreign-object c-str) + str))) + + @@ -1311,7 +1880,7 @@ that returns a cstring. Side Effects - None. + On some implementations, this function allocates memory. Affected by @@ -1353,7 +1922,7 @@ that returns a cstring. Description Frees any memory possibly allocated by - convert-to-cstring. + convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. @@ -1413,7 +1982,7 @@ that returns a cstring. Description - Binds a lexical variable to a newly allocated cstring. Automatically frees cstring. + Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. @@ -1599,7 +2168,7 @@ Can translated ASCII and binary strings. unsigned - A boolean flag with a default value of &nil;. When true, + A boolean flag with a default value of &t;. When true, marks the pointer as an :unsigned-char. @@ -1665,7 +2234,7 @@ marks the pointer as an :unsigned-char. args - A list of argument declarations. Use &nil; to specify no arguments. + A list of argument declarations. If &nil;, indicates that the function does not take any arguments. @@ -1679,7 +2248,7 @@ marks the pointer as an :unsigned-char. returning A declaration specifying the result type of the -foreign function. +foreign function. If :void indicates module does not return any value. @@ -1694,7 +2263,7 @@ foreign function. Examples (def-function "gethostname" - ((name :cstring) + ((name (* :unsigned-char)) (len :int)) :returning :int) @@ -1723,7 +2292,7 @@ foreign function. Syntax - load-foreign-library filename &key module supporting-libraries => success + load-foreign-library filename &key module supporting-libraries force-load => success @@ -1754,6 +2323,13 @@ link the foreign library. (Required by CMUCL) + + force-load + + Forces the loading of the library if it has been previously loaded. + + + success @@ -1769,7 +2345,7 @@ 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. +a session. A library can be reloaded by using the :force-load key. @@ -1796,6 +2372,91 @@ a session. + + + find-foreign-library + Finds a foreign library file. + + Function + + + Syntax + + find-foreign-library names directories & drive-letters types => path + + + + Arguments and Values + + + names + + A string or list of strings containing the base name of the library file. + + + + + directories + + A string or list of strings containing the directory the library file. + + + + + drive-letters + + A string or list of strings containing the drive letters for the library file. + + + + + types + + A string or list of strings containing the file type of the library file. Default +is &nil;. If &nil;, will use a default type based on the currently running implementation. + + + + + path + + A path containing the path found, or &nil; if the library file was not found. + + + + + + + Description + Finds a foreign library by searching through a number of possible locations. Returns +the path of the first found file. + + + + Examples + +(find-foreign-library '("libmysqlclient" "libmysql") + '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/") + :types '("so" "dll") + :drive-letters '("C" "D" "E")) +=> #P"D:\\mysql\\lib\\opt\\libmysql.dll" + + + + Side Effects + None. + + + + Affected by + None. + + + Exceptional Situations + None. + + +