4.4 The Inspector

4.4.3 Inspecting foreign pointers

The Inspector can be called on Lisp objects called foreign pointers, which are part of the Foreign Function Interface. This section provides a detailed example of calling the Inspector on a foreign pointer; beginning Lisp users can skip this discussion.

The Liquid Common Lisp Foreign Function Interface loads code that is written in computer languages other than Lisp into the Lisp environment and allows you to manipulate foreign data objects. Foreign pointers are Lisp objects whose structure is defined by the macrodef-foreign-struct. Lisp treats all foreign data objects as foreign pointers, which can be passed as Lisp objects and inspected. Foreign pointer components have the following format in the Inspector:

Pointers with a foreign structure type created by the macrodef-foreign-struct are displayed in the following format:

: [entry-number: slot-name (hex-byte-offset-in-struct)] entry

Multidimensional arrays of any type other than:character are displayed in the following format:

: [entry-number]Indices: index-tuple entry

Arrays of any dimension of type:character and elements of type:pointer :character are displayed as strings.

The following terminal session shows an example of inspecting a foreign pointer.

;; Create a foreign type with four slots.
> (def-foreign-struct inspect-example
    (slot-1 :type (:array :unsigned-16bit (2 2)))
    (slot-2 :type (:array :character (16)))
    (slot-3 :type :signed-32bit :overlays slot-1)
    (slot-4 :type :double-float))
INSPECT-EXAMPLE

> (setq *print-base* 16)
10

;; Create an instance of the foreign type.
> (defparameter *inspect-example*
    (make-inspect-example :slot-3 #x12345678 :slot-4 pi))
*INSPECT-EXAMPLE*

;; Now inspect the foreign pointer object.  Note the following 
;; about the pointer's slots: 
;; Slot-2 starts 8 bytes after the start of the structure 
;; because slot-1 occupies 8 bytes.
;; Slot-3 overlays slot-1 and so occupies the first 4 of
;; slot-1's 8 bytes.
;; Slot-2 is #x10 bytes long, which added to slot-1's 8
;; bytes means that slot-4 starts at #x18 bytes.
> (inspect *inspect-example*)
#<Foreign-Pointer 626060 (:POINTER INSPECT-EXAMPLE)>
[0: SLOT-1 (0)] #<Foreign-Pointer 626060 (:POINTER (:ARRAY :UNSIGNED-16BIT (2 2)))>
[1: SLOT-2 (8)] #<Foreign-Pointer 626068 (:POINTER (:ARRAY :CHARACTER (10)))>
[2: SLOT-3 (0)] 12345678
[3: SLOT-4 (18)] 3.141592653589793

>> 0
#<Foreign-Pointer 626060 (:POINTER (:ARRAY :UNSIGNED-16BIT (2 2)))>
[0] Indices: (0 0) +++ Conditional TRUE: (or sgi es rs)  1234
[1] Indices: (0 1) +++ Conditional TRUE: (or sgi es rs)  5678
[2] Indices: (1 0) 0
[3] Indices: (1 1) 0

>> :s 1 #x4321
#<Foreign-Pointer 626060 (:POINTER (:ARRAY :UNSIGNED-16BIT (2 2)))>
[0] Indices: (0 0) +++ Conditional TRUE: (or sgi es rs)  1234
[1] Indices: (0 1) 4321
[2] Indices: (1 0) 0
[3] Indices: (1 1) 0

>> :u
#<Foreign-Pointer 626060 (:POINTER INSPECT-EXAMPLE)>
[0: SLOT-1 (0)] #<Foreign-Pointer 626060 (:POINTER (:ARRAY :UNSIGNED-16BIT (2 2)))>
[1: SLOT-2 (8)] #<Foreign-Pointer 626068 (:POINTER (:ARRAY :CHARACTER (10)))>
;; Note that the value of slot-3 has changed, as this slot 
;; overlays slot-1, which was changed just above.
[2: SLOT-3 (0)] +++ Conditional TRUE: (or sgi es rs)  12344321
[3: SLOT-4 (18)] 3.141592653589793

>> 1
#<Foreign-Pointer 626068 (:POINTER (:ARRAY :CHARACTER (10)))>
;; The slot initially contains #x10 null characters.
[0] "^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@^@"

>> :s 0 "this is just a test string"
#<Foreign-Pointer 626068 (:POINTER (:ARRAY :CHARACTER (10)))>
;; The characters in slot-2 are replaced by the first
;; #x10 in the  test string.
[0] "this is just a t"

>> :q
#<Foreign-Pointer 626068 (:POINTER (:ARRAY :CHARACTER (10)))>

For more information about the Foreign Function Interface, see Chapter 4, "Working Beyond the Lisp Environment" in The Advanced User's Guide.

The User's Guide - 9 SEP 1996

Generated with Harlequin WebMaker