Wrapped pointers are untyped, so they are essentially equivalent to C
void pointers. As in C, the memory region pointed to by a
pointer can be accessed at the byte level. This is achieved using
bytevectors (see Bytevectors). The
module contains procedures that can be used to convert byte sequences to
Scheme objects such as strings, floating point numbers, or integers.
(system foreign) module to use these Scheme interfaces.
(use-modules (system foreign))
Return a bytevector aliasing the len bytes pointed to by pointer.
The user may specify an alternate default interpretation for the memory
by passing the uvec_type argument, to indicate that the memory is
an array of elements of that type. uvec_type should be something
array-type would return, like
When offset is passed, it specifies the offset in bytes relative to pointer of the memory region aliased by the returned bytevector.
Mutating the returned bytevector mutates the memory pointed to by pointer, so buckle your seatbelts.
Return a pointer pointer aliasing the memory pointed to by bv or offset bytes after bv when offset is passed.
In addition to these primitives, convenience procedures are available:
Assuming pointer points to a memory region that holds a pointer, return this pointer.
Return a foreign pointer to a nul-terminated copy of string in the given encoding, defaulting to the current locale encoding. The C string is freed when the returned foreign pointer becomes unreachable.
This is the Scheme equivalent of
Return the string representing the C string pointed to by pointer.
If length is omitted or
-1, the string is assumed to be
nul-terminated. Otherwise length is the number of bytes in memory
pointed to by pointer. The C string is assumed to be in the given
encoding, defaulting to the current locale encoding.
This is the Scheme equivalent of
Most object-oriented C libraries use pointers to specific data
structures to identify objects. It is useful in such cases to reify the
different pointer types as disjoint Scheme types. The
define-wrapped-pointer-type macro simplifies this.
Define helper procedures to wrap pointer objects into Scheme objects with a disjoint type. Specifically, this macro defines:
wrap preserves pointer identity, for two pointer objects p1
and p2 that are
(eq? (wrap p1)
(wrap p2)) ⇒ #t.
Finally, print should name a user-defined procedure to print such objects. The procedure is passed the wrapped object and a port to write to.
For example, assume we are wrapping a C library that defines a type,
bottle_t, and functions that can be passed
pointers to manipulate them. We could write:
(define-wrapped-pointer-type bottle bottle? wrap-bottle unwrap-bottle (lambda (b p) (format p "#<bottle of ~a ~x>" (bottle-contents b) (pointer-address (unwrap-bottle b))))) (define grab-bottle ;; Wrapper for `bottle_t *grab (void)'. (let ((grab (foreign-library-function libbottle "grab_bottle" #:return-type '*))) (lambda () "Return a new bottle." (wrap-bottle (grab))))) (define bottle-contents ;; Wrapper for `const char *bottle_contents (bottle_t *)'. (let ((contents (foreign-library-function libbottle "bottle_contents" #:return-type '* #:arg-types '(*)))) (lambda (b) "Return the contents of B." (pointer->string (contents (unwrap-bottle b)))))) (write (grab-bottle)) ⇒ #<bottle of Château Haut-Brion 803d36>
In this example,
grab-bottle is guaranteed to return a genuine
bottle object satisfying
bottle-contents errors out when its argument is not a genuine
As another example, currently Guile has a variable,
as part of its API. It is declared as a C
long. So, to read its
value, we can do:
(use-modules (system foreign)) (use-modules (rnrs bytevectors)) (define numptob (foreign-library-pointer #f "scm_numptob")) numptob (bytevector-uint-ref (pointer->bytevector numptob (sizeof long)) 0 (native-endianness) (sizeof long)) ⇒ 8
If we wanted to corrupt Guile’s internal state, we could set
scm_numptob to another value; but we shouldn’t, because that
variable is not meant to be set. Indeed this point applies more widely:
the C API is a dangerous place to be. Not only might setting a value
crash your program, simply accessing the data pointed to by a dangling
pointer or similar can prove equally disastrous.