From: Kevin M. Rosenberg Date: Thu, 13 Nov 2003 15:26:07 +0000 (+0000) Subject: r8185: convert programlisting to screen X-Git-Tag: v1.6.1~146 X-Git-Url: http://git.kpe.io/?p=uffi.git;a=commitdiff_plain;h=e23ce13827d1948c2e46f2b36a4a22127615844a r8185: convert programlisting to screen --- diff --git a/doc/bookinfo.xml b/doc/bookinfo.xml index 0ae6142..42044c3 100644 --- a/doc/bookinfo.xml +++ b/doc/bookinfo.xml @@ -49,25 +49,27 @@ - Allegro CL® is a registered + + Allegro CL® is a registered trademark of Franz Inc. - Lispworks® is a registered + + Lispworks® is a registered trademark of Xanalys Inc. - Microsoft - Windows® is a registered trademark of - Microsoft Inc. + + Microsoft Windows® is a + registered trademark of Microsoft Inc. - Other brand or - product names are the registered trademarks or trademarks of - their respective holders. + + Other brand or product names are the registered trademarks + or trademarks of their respective holders. diff --git a/doc/notes.xml b/doc/notes.xml index 139267e..7d6d366 100644 --- a/doc/notes.xml +++ b/doc/notes.xml @@ -81,12 +81,12 @@ Here is an example that should both methods being used for maximum cross-implementation optimization: - + (uffi:def-type the-struct-type-def the-struct-type) (let ((a-foreign-struct (allocate-foreign-object 'the-struct-type))) (declare 'the-struct-type-def a-foreign-struct) (get-slot-value a-foreign-struct 'the-struct-type 'field-name)) - + diff --git a/doc/ref_aggregate.xml b/doc/ref_aggregate.xml index 75c384f..5aa8644 100644 --- a/doc/ref_aggregate.xml +++ b/doc/ref_aggregate.xml @@ -70,7 +70,7 @@ a foreign type with the name name of type Examples - + (def-enum abc (:a :b :c)) ;; Creates constants abc#a (1), abc#b (2), abc#c (3) and defines ;; the foreign type "abc" to be :int @@ -78,7 +78,7 @@ a foreign type with the name name of type (def-enum efoo (:e1 (:e2 10) :e3) :separator-string "-") ;; Creates constants efoo-e1 (1), efoo-e2 (10), efoo-e3 (11) and defines ;; the foreign type efoo to be :int - + Side Effects @@ -138,12 +138,12 @@ structure. It's type is :pointer-self. Examples - + (def-struct foo (a :unsigned-int) (b (* :char)) (c (:array :int 10)) (next :pointer-self)) - + Side Effects @@ -214,9 +214,9 @@ structure. It's type is :pointer-self. Examples - + (get-slot-value foo-ptr 'foo-structure 'field-name) - + Side Effects @@ -287,9 +287,9 @@ structure. It's type is :pointer-self. Examples - + (get-slot-pointer foo-ptr 'foo-structure 'my-char-ptr) - + Side Effects @@ -346,9 +346,9 @@ structure. It's type is :pointer-self. Examples - + (def-array-pointer byte-array-pointer :unsigned-char) - + Side Effects @@ -420,14 +420,14 @@ the array. Examples - + (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)))) => &nil; &t; - + Notes @@ -491,7 +491,7 @@ the array. Examples - + (def-union test-union (a-char :char) (an-int :int)) @@ -502,7 +502,7 @@ the array. (ensure-char-character (get-slot-value u 'test-union 'a-char)) (free-foreign-object u))) => #\A - + Side Effects diff --git a/doc/ref_declare.xml b/doc/ref_declare.xml index 1e40da6..ddbd818 100644 --- a/doc/ref_declare.xml +++ b/doc/ref_declare.xml @@ -57,13 +57,13 @@ Examples - + (def-type char-ptr '(* :char)) ... (defun foo (ptr) (declare (type char-ptr ptr)) ... - + Side Effects diff --git a/doc/ref_func_libr.xml b/doc/ref_func_libr.xml index 0e48d59..7a366db 100644 --- a/doc/ref_func_libr.xml +++ b/doc/ref_func_libr.xml @@ -61,12 +61,12 @@ foreign function. If :void indicates module does not return Examples - + (def-function "gethostname" ((name (* :unsigned-char)) (len :int)) :returning :int) - + Side Effects @@ -150,12 +150,12 @@ a session. A library can be reloaded by using the :force-load k Examples - + (load-foreign-library #p"/usr/lib/libmysqlclient.so" :module "mysql" :supporting-libraries '("c")) => T - + Side Effects @@ -234,13 +234,13 @@ 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 diff --git a/doc/ref_object.xml b/doc/ref_object.xml index 226f0be..8931219 100644 --- a/doc/ref_object.xml +++ b/doc/ref_object.xml @@ -64,11 +64,11 @@ array of type that is size members Examples - + (def-struct ab (a :int) (b :double)) (allocate-foreign-object 'ab) => #<ptr> - + Side Effects @@ -181,14 +181,14 @@ 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 @@ -238,12 +238,12 @@ much better with static allocation. Examples - + (size-of-foreign-object :unsigned-byte) => 1 (size-of-foreign-object 'my-100-byte-vector-type) => 100 - + @@ -360,14 +360,14 @@ much better with static allocation. Examples - + (let ((intp (allocate-foreign-object :int))) (setf (deref-pointer intp :int) 10) (prog1 (deref-pointer intp :int) (free-foreign-object intp))) => 10 - + @@ -436,13 +436,13 @@ 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 - + @@ -504,13 +504,13 @@ an integer. Examples - + (let ((fs (convert-to-foreign-string "a"))) (prog1 (ensure-char-integer (deref-pointer fs :char)) (free-foreign-object fs))) => 96 - + @@ -710,7 +710,7 @@ if a cstring returned by a function is &null;. Examples - + (with-foreign-object (size :int) ;; FOO is a foreign function returning a :POINTER-VOID (let ((memory (foo size))) @@ -721,7 +721,7 @@ if a cstring returned by a function is &null;. (dotimes (i (deref-pointer size :int)) (do-something-with (deref-array memory '(:array :unsigned-byte) i))))))) - + Side Effects @@ -796,7 +796,7 @@ value of a variable in foreign code. Examples C code - + int baz = 3; typedef struct { @@ -809,11 +809,11 @@ value of a variable in foreign code. int foo () { return baz; } - + Lisp code - + (uffi:def-struct foo-struct (x :int) (y :double)) @@ -835,7 +835,7 @@ value of a variable in foreign code. (foo) => 4 - + diff --git a/doc/ref_primitive.xml b/doc/ref_primitive.xml index 8ab1286..eed908c 100644 --- a/doc/ref_primitive.xml +++ b/doc/ref_primitive.xml @@ -126,10 +126,10 @@ Examples - + (def-constant pi2 (* 2 pi)) (def-constant exported-pi2 (* 2 pi) :export t) - + Side Effects @@ -185,11 +185,11 @@ Examples - + (def-foreign-type my-generic-pointer :pointer-void) (def-foreign-type a-double-float :double-float) (def-foreign-type char-ptr (* :char)) - + Side Effects @@ -253,14 +253,14 @@ Examples - + (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)))) => &nil; &t; - + Side Effects diff --git a/doc/ref_string.xml b/doc/ref_string.xml index 1941614..d488e12 100644 --- a/doc/ref_string.xml +++ b/doc/ref_string.xml @@ -6,42 +6,41 @@ ]> - Strings - -Overview - - - &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. - - - + Strings + + Overview + + &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) + ((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. + + 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)) @@ -56,14 +55,16 @@ string for a return value. (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. + + 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)) @@ -75,21 +76,23 @@ following is an example of handling such a function. (str (convert-from-foreign-string c-str))) (uffi:free-foreign-object c-str) str))) - - - - + + + + convert-from-cstring - Converts a cstring to a Lisp string. - + Converts a cstring to a Lisp string. Macro Syntax - convert-from-cstring cstring => string + convert-from-cstring + cstring + => + string @@ -115,8 +118,8 @@ following is an example of handling such a function. Description Converts a Lisp string to a cstring. This is -most often used when processing the results of a foreign function -that returns a cstring. + most often used when processing the results of a foreign function + that returns a cstring. @@ -131,161 +134,163 @@ that returns a cstring. Exceptional Situations None. - - - - - - convert-to-cstring - Converts a Lisp string to a cstring. - - Macro - - - Syntax - - convert-to-cstring string => cstring - - - - Arguments and Values - - - string - - A Lisp string. - - - - - cstring - - A cstring. - - - - - - - Description - - Converts a Lisp string to a - cstring. The - cstring should be freed with - free-cstring. - - - - Side Effects - On some implementations, this function allocates memory. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - free-cstring - Free memory used by cstring. - - Macro - - - Syntax - - free-cstring cstring - - - - Arguments and Values - - - cstring - - A cstring. - - - - - - - Description - - Frees any memory possibly allocated by - convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - with-cstring - Binds a newly created cstring. - - Macro - - - Syntax - - with-cstring (cstring string) {body} - - - - Arguments and Values - - - cstring - - A symbol naming the cstring to be created. - - - - - string - - A Lisp string that will be translated to a cstring. - - - - - body - - The body of where the cstring will be bound. - - - - - - - Description - - Binds a symbol to a cstring created from conversion of a string. Automatically frees the cstring. - - - - Examples - - + + + + + + convert-to-cstring + Converts a Lisp string to a cstring. + Macro + + + Syntax + + convert-to-cstring + string + => + cstring + + + + Arguments and Values + + + string + + A Lisp string. + + + + + cstring + + A cstring. + + + + + + + Description + + Converts a Lisp string to a cstring. The + cstring should be freed with + free-cstring. + + + + Side Effects + On some implementations, this function allocates memory. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + free-cstring + Free memory used by cstring. + + Macro + + + Syntax + + free-cstring cstring + + + + Arguments and Values + + + cstring + + A cstring. + + + + + + + Description + + Frees any memory possibly allocated by + convert-to-cstring. On some implementions, a cstring is just the Lisp string itself. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + with-cstring + Binds a newly created cstring. + Macro + + + Syntax + + with-cstring + (cstring string) {body} + + + + Arguments and Values + + + cstring + + A symbol naming the cstring to be created. + + + + + string + + A Lisp string that will be translated to a cstring. + + + + + body + + The body of where the cstring will be bound. + + + + + + + Description + + Binds a symbol to a cstring created from conversion of a + string. Automatically frees the cstring. + + + + Examples + + (def-function ("getenv" c-getenv) ((name :cstring)) :returning :cstring) @@ -295,209 +300,213 @@ that returns a cstring. (check-type key string) (with-cstring (key-cstring key) (convert-from-cstring (c-getenv key-cstring)))) - - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - convert-from-foreign-string - Converts a foreign string into a Lisp string. - - Macro - - - Syntax - - convert-from-foreign-string foreign-string &key length null-terminated-p => string - - - - Arguments and Values - - - foreign-string - - A foreign string. - - - - - length - - The length of the foreign string to -convert. The default is the length of the string until a &null; -character is reached. - - - - - null-terminated-p - - A boolean flag with a default value of &t; When true, -the string is converted until the first &null; character is reached. - - - - - string - - A Lisp string. - - - - - - - Description - - Returns a Lisp string from a foreign string. -Can translated ASCII and binary strings. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - convert-to-foreign-string - Converts a Lisp string to a foreign string. - - Macro - - - Syntax - - convert-to-foreign-string string => foreign-string - - - - Arguments and Values - - - string - - A Lisp string. - - - - - foreign-string - - A foreign string. - - - - - - - Description - - Converts a Lisp string to a foreign string. Memory should be - freed with free-foreign-object. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - - - - - allocate-foreign-string - Allocates space for a foreign string. - - Macro - - - Syntax - - allocate-foreign-string size &key unsigned => foreign-string - - - - Arguments and Values - - - size - - The size of the space to be allocated in bytes. - - - - - unsigned - - A boolean flag with a default value of &t;. When true, -marks the pointer as an :unsigned-char. - - - - - foreign-string - - A foreign string which has undefined contents. - - - - - - - Description - - Allocates space for a foreign string. Memory should - be freed with free-foreign-object. - - - - Side Effects - None. - - - Affected by - None. - - - Exceptional Situations - None. - - - - + + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-from-foreign-string + Converts a foreign string into a Lisp string. + Macro + + + Syntax + + convert-from-foreign-string + foreign-string &key length null-terminated-p + => + string + + + + Arguments and Values + + + foreign-string + + A foreign string. + + + + + length + + The length of the foreign string to convert. The + default is the length of the string until a &null; + character is reached. + + + + + null-terminated-p + + A boolean flag with a default value of &t; When true, + the string is converted until the first &null; character is reached. + + + + + string + + A Lisp string. + + + + + + + Description + + Returns a Lisp string from a foreign string. + Can translated ASCII and binary strings. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + + convert-to-foreign-string + Converts a Lisp string to a foreign string. + + Macro + + + Syntax + + convert-to-foreign-string + string => + foreign-string + + + + Arguments and Values + + + string + + A Lisp string. + + + + + foreign-string + + A foreign string. + + + + + + + Description + + Converts a Lisp string to a foreign string. Memory should be + freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + + + + allocate-foreign-string + Allocates space for a foreign string. + + Macro + + + Syntax + + allocate-foreign-string size + &key unsigned => + foreign-string + + + + Arguments and Values + + + size + + The size of the space to be allocated in bytes. + + + + + unsigned + + A boolean flag with a default value of &t;. When true, + marks the pointer as an :unsigned-char. + + + + + foreign-string + + A foreign string which has undefined contents. + + + + + + + Description + + Allocates space for a foreign string. Memory should + be freed with free-foreign-object. + + + + Side Effects + None. + + + Affected by + None. + + + Exceptional Situations + None. + + + +