Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.

6.20.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.