dereference Accessor

Summary

Accesses and returns the value of a foreign object.

Package

fli

Signature

dereference pointer &key index type copy-foreign-object => value

setf (dereference pointer &key index type copy-foreign-object) value => value

Arguments

Values

Description

The accessor dereference accesses and returns the value of the FLI object pointed to by pointer.

If index is supplied, dereference assumes that pointer points to one element in an array of object, and returns the element with index index in the array.

If type is supplied, then dereference assumes that pointer points to an object of that type, overriding the type in pointer itself.

copy-foreign-object is only used when the type of pointer (or type if supplied) is an aggregate type, because objects of these types cannot be converted to a Lisp value. If copy-foreign-object is t, dereference makes a copy of the aggregate object pointed to by pointer and returns the copy. If copy-foreign-object is nil, dereference returns the aggregate object directly. If copy-foreign-object is :error (the default) then dereference signals an error.

The value of an object at pointer can be changed using the setf form of dereference. See the examples section for an example of this.

An error is signaled if pointer is a null pointer. You can use null-pointer-p to detect null pointers.

Compatibility note

64-bit integer types such as (:long :long), :int64 and :uint64 are now supported for type in dereference in 32-bit LispWorks. In 32-bit LispWorks 6.1 and earlier versions, these types could only be used by define-foreign-function.

Examples

In the following example a LONG type is defined and an instance, pointed to by point, with a specified initial value of 10 is created with memory allocated using allocate-foreign-object. The dereference function is then used to get the value that point points to.

(fli:define-c-typedef LONG :long)

(setq point (fli:allocate-foreign-object
             :type 'LONG
             :initial-element 10))

(fli:dereference point)

Finally, the value of the object of type LONG is changed to 20 using the setf form of dereference.

(setf (fli:dereference point) 20)

In the next example, a boolean FLI type is defined, but is accessed as a char.

(fli:define-c-typedef BOOL (:boolean :int))

(setq point2 (fli:allocate-foreign-object :type 'BOOL))

(fli:dereference point2 :type :char)

See also

allocate-foreign-object
free-foreign-object
foreign-slot-value
null-pointer-p
2 FLI Types
3.3 Pointer dereferencing and coercing
5.2.5 Calling a C function that takes an array of strings