From: Kevin M. Rosenberg Date: Thu, 21 Mar 2002 08:11:52 +0000 (+0000) Subject: r1602: Updated doc X-Git-Tag: v1.6.1~564 X-Git-Url: http://git.kpe.io/?p=uffi.git;a=commitdiff_plain;h=d3f9b63d9227cc2fb7b978e4b40b9592c04852ab r1602: Updated doc --- diff --git a/ChangeLog b/ChangeLog index 1d69f94..e69da6a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -7,6 +7,9 @@ See TODO file -- actively maintained. Includes changes that you of UFFI. Builds on UNIX and Win32 platforms. * Added def-union function, added union.cl example * Fixed error with ensure-char-[character|integer] + * Added 2-d array example to examples/arrays.cl + * Fixed documentation error on gethostname + * Added ensure-char-* and def-union to documentation 20 Mar 2002 * Updated strings.cl so that foreign-strings are always unsigned. diff --git a/doc/ref.sgml b/doc/ref.sgml index e8c45fd..82ee66a 100644 --- a/doc/ref.sgml +++ b/doc/ref.sgml @@ -776,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. + + + + @@ -783,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. @@ -979,7 +1049,7 @@ the array. - value + value The value of the object where the pointer points. @@ -997,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 @@ -1015,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. + @@ -1638,7 +1845,7 @@ foreign function. If :void indicates module does not return Examples (def-function "gethostname" - ((name :cstring) + ((name (* :unsigned-char)) (len :int)) :returning :int)