X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref.sgml;h=82ee66a5df717e7d9ed15cbbfa5e3d8d607c39f1;hb=d3f9b63d9227cc2fb7b978e4b40b9592c04852ab;hp=46f91a5f40fbc037a1ef6b5f35c6df46dabd3bbd;hpb=76ae1bdbadaaf87603ebbe987e59dd1a105f1872;p=uffi.git diff --git a/doc/ref.sgml b/doc/ref.sgml index 46f91a5..82ee66a 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -88,43 +88,53 @@ - :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 - Unsigned 8-bits. A +dereferenced :byte pointer returns an integer. - :unsigned-short - Unsigned 16-bits + :short - Signed 16-bits. - :int - Signed 32-bits + :unsigned-short - Unsigned 16-bits. - :unsigned-int - Unsigned 32-bits + :int - Signed 32-bits. - :long - Signed 32-bits + :unsigned-int - Unsigned 32-bits. - :unsigned-long - Unsigned 32-bits + :long - Signed 32-bits. - :float - 32-bit floating point + :unsigned-long - Unsigned 32-bits. - :double - 64-bit floating point + :float - 32-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 @@ -327,86 +337,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 +496,7 @@ structure. It's type is :pointer-self. - def-slot-value + get-slot-value Retrieves a value from a slot of a structure. Macro @@ -832,6 +776,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 +852,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. @@ -886,7 +900,7 @@ the array. Examples (def-struct ab (a :int) (b :double)) -(allocate-foreign-object 'ab) +(allocate-foreign-object ab) => #<ptr> @@ -1014,7 +1028,7 @@ the array. Syntax - def-pointer ptr type => value + deref-pointer ptr type => value @@ -1035,7 +1049,7 @@ the array. - value + value The value of the object where the pointer points. @@ -1053,9 +1067,76 @@ the array. Examples +(let ((intp (allocate-foreign-object :int))) + (setf (deref-pointer intp :int) 10) + (prog1 + (deref-pointer intp :int) + (free-foreign-object intp))) +=> 10 + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + ensure-char-character + Ensures that a dereferenced :char pointer is +a character. + + 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 + + Ensures that an object obtained by dereferencing a +:char pointer is a character. + + + + Examples + + (let ((fs (convert-to-foreign-string "a"))) (prog1 - (ensure-char (deref-pointer fs :char)) + (ensure-char-character (deref-pointer fs :char)) (free-foreign-object fs))) => #\a @@ -1071,8 +1152,78 @@ the array. 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. + @@ -1599,7 +1750,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 +1816,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 +1830,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 +1845,7 @@ foreign function. Examples (def-function "gethostname" - ((name :cstring) + ((name (* :unsigned-char)) (len :int)) :returning :int)