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 (rnrs bytevectors)
module contains procedures that can be used to convert byte sequences to
Scheme objects such as strings, floating point numbers, or integers.
Load the (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
that array-type
would return, like f32
or s16
.
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 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 scm_to_stringn
.
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 scm_from_stringn
.
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 equal?
, (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 bottle_t *
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?
. Likewise,
bottle-contents
errors out when its argument is not a genuine
bottle
object.
As another example, currently Guile has a variable, scm_numptob
,
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.