%eclent; ]> Objects are entities that can allocated, referred to by pointers, and can be freed. allocate-foreign-object Allocates an instance of a foreign object. allocate-foreign-object type &optional; size type 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. returns A pointer to the foreign object. Allocates an instance of a foreign object. It returns a pointer to the object. (def-struct ab (a :int) (b :double)) (allocate-foreign-object 'ab) => #<ptr> None. None. None. free-foreign-object Frees memory that was allocated for a foreign boject. free-foreign-object ptr ptr A pointer to the allocated foreign object to free. Frees the memory used by the allocation of a foreign object. None. None. None. with-foreign-object Wraps the allocation of a foreign object around a body of code. with-foreign-object (var type) &body; body var The variable name to bind. type The type of foreign object to allocate. This parameter is evaluated. returns The result of evaluating the body. 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. (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.")))) None. None. None. size-of-foreign-type Returns the number of data bytes used by a foreign object type. size-of-foreign-type ftype ftype A foreign type specifier. This parameter is evaluated. Returns the number of data bytes used by a foreign object type. This does not include any Lisp storage overhead. (size-of-foreign-object :unsigned-byte) => 1 (size-of-foreign-object 'my-100-byte-vector-type) => 100 None. None. None. pointer-address Returns the address of a pointer. pointer-address ptr ptr A pointer to a foreign object. returns An integer representing the pointer's address. Returns the address as an integer of a pointer. None. None. None. deref-pointer Deferences a pointer. deref-pointer ptr type ptr A pointer to a foreign object. type A foreign type of the object being pointed to. returns The value of the object where the pointer points. Returns the object to which a pointer points. (let ((intp (allocate-foreign-object :int))) (setf (deref-pointer intp :int) 10) (prog1 (deref-pointer intp :int) (free-foreign-object intp))) => 10 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. None. None. None. ensure-char-character Ensures that a dereferenced :char pointer is a character. ensure-char-character object object Either a character or a integer specifying a character code. returns A character. Ensures that an objects obtained by dereferencing :char and :unsigned-char pointers are a lisp character. (let ((fs (convert-to-foreign-string "a"))) (prog1 (ensure-char-character (deref-pointer fs :char)) (free-foreign-object fs))) => #\a None. None. 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. ensure-char-integer object object Either a character or a integer specifying a character code. returns An integer. Ensures that an object obtained by dereferencing a :char pointer is an integer. (let ((fs (convert-to-foreign-string "a"))) (prog1 (ensure-char-integer (deref-pointer fs :char)) (free-foreign-object fs))) => 96 None. None. 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. make-null-pointer type type A type of object to which the pointer refers. returns The &NULL; pointer of type type. Creates a &NULL; pointer of a specified type. None. None. None. null-pointer-p Tests a pointer for &NULL; value. null-pointer-p ptr ptr A foreign object pointer. returns The boolean flag. A predicate testing if a pointer is has a &NULL; value. None. None. None. +null-cstring-pointer+ A constant &NULL; cstring pointer. Constant 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. with-cast-pointer (binding-name ptr type) &body; body binding-name A symbol which will be bound to the casted object. ptr A pointer to a foreign object. type A foreign type of the object being pointed to. returns The value of the object where the pointer points. Executes BODY with POINTER cast to be a pointer to type TYPE. BINDING-NAME is will be bound to this value 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. (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))))))) None. None. None. def-foreign-var Defines a symbol macro to access a variable in foreign code def-foreign-var name type module 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) Defines a symbol macro which can be used to access (get and set) the value of a variable in foreign code. int baz = 3; typedef struct { int x; double y; } foo_struct; foo_struct the_struct = { 42, 3.2 }; int foo () { return baz; } (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 None. None. None.