6.19.3 Foreign Pointers

Foreign libraries are essentially key-value mappings, where the keys are names of definitions and the values are the addresses of those definitions. To look up the address of a definition, use foreign-library-pointer from the (system foreign-library) module.

Scheme Procedure: foreign-library-pointer lib name ¶

Return a “wrapped pointer” for the symbol name in the shared object referred to by lib. The returned pointer points to a C object.

As a convenience, if lib is not a foreign library, it will be passed to load-foreign-library.

If we continue with the bessel.so example from before, we can get the address of the init_math_bessel function via:

(use-modules (system foreign-library))
(define init (foreign-library-pointer "bessel" "init_math_bessel"))
init
⇒ #<pointer 0x7fb35b1b4688>

A value returned by foreign-library-pointer is a Scheme wrapper for a C pointer. Pointers are a data type in Guile that is disjoint from all other types. The next section discusses ways to dereference pointers, but before then we describe the usual type predicates and so on.

Note that the rest of the interfaces in this section are part of the (system foreign) library:

(use-modules (system foreign))

Scheme Procedure: pointer-address pointer ¶

C Function: scm_pointer_address (pointer) ¶

Return the numerical value of pointer.

(pointer-address init)
⇒ 139984413364296 ; YMMV

Scheme Procedure: make-pointer address [finalizer] ¶

Return a foreign pointer object pointing to address. If finalizer is passed, it should be a pointer to a one-argument C function that will be called when the pointer object becomes unreachable.

Scheme Procedure: pointer? obj ¶

Return #t if obj is a pointer object, or #f otherwise.

Scheme Variable: %null-pointer ¶

A foreign pointer whose value is 0.

Scheme Procedure: null-pointer? pointer ¶

Return #t if pointer is the null pointer, #f otherwise.

For the purpose of passing SCM values directly to foreign functions, and allowing them to return SCM values, Guile also supports some unsafe casting operators.

Scheme Procedure: scm->pointer scm ¶

Return a foreign pointer object with the object-address of scm.

Scheme Procedure: pointer->scm pointer ¶

Unsafely cast pointer to a Scheme object. Cross your fingers!

Sometimes you want to give C extensions access to the dynamic FFI. At that point, the names get confusing, because “pointer” can refer to a SCM object that wraps a pointer, or to a void* value. We will try to use “pointer object” to refer to Scheme objects, and “pointer value” to refer to void * values.

C Function: SCM scm_from_pointer (void *ptr, void (*finalizer) (void*)) ¶

Create a pointer object from a pointer value.

If finalizer is non-null, Guile arranges to call it on the pointer value at some point after the pointer object becomes collectable.

C Function: void* scm_to_pointer (SCM obj) ¶

Unpack the pointer value from a pointer object.