6.21.5.2 Foreign Variables

Pointers to variables in the current address space may be looked up dynamically using dynamic-pointer.

Scheme Procedure: dynamic-pointer name dobj

C Function: scm_dynamic_pointer (name, dobj)

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

Regardless whether your C compiler prepends an underscore ‘_’ to the global names in a program, you should not include this underscore in name since it will be added automatically when necessary.

For example, currently Guile has a variable, scm_numptob, as part of its API. It is declared as a C long. So, to create a handle pointing to that foreign value, we do:

(use-modules (system foreign))
(define numptob (dynamic-pointer "scm_numptob" (dynamic-link)))
numptob
⇒ #<pointer 0x7fb35b1b4688>

(The next section discusses ways to dereference pointers.)

A value returned by dynamic-pointer is a Scheme wrapper for a C pointer.

Scheme Procedure: pointer-address pointer

C Function: scm_pointer_address (pointer)

Return the numerical value of pointer.

(pointer-address numptob)
⇒ 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, #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.