►The Racket Foreign Interface
▼3 C Types
On this page:
_ pointer
_ gcpointer
_ racket
_ scheme
_ fpointer
_ or-null
_ gcable
  top  ← prev  up  next → 

3.5 Pointer Types

value

_pointer : ctype?

Corresponds to Racket C pointer values. These pointers can have an arbitrary Racket object attached as a type tag. The tag is ignored by built-in functionality; it is intended to be used by interfaces. See Tagged C Pointer Types for creating pointer types that use these tags for safety. A #f value is converted to NULL and vice versa.

The address referenced by a _pointer value must not refer to memory managed by the garbage collector (unless the address corresponds to a value that supports interior pointers and that is otherwise referenced to preserve the value from garbage collection). The reference is not traced or updated by the garbage collector.

The equal? predicate equates C pointers (including pointers for _gcpointer and possibly containing an offset) when they refer to the same address.

value

_gcpointer : ctype?

Like _pointer, but for a C pointer value that can refer to memory managed by the garbage collector.

Although a _gcpointer can reference to memory that is not managed by the garbage collector, beware of using an address that might eventually become managed by the garbage collector. For example, if a reference is created by malloc with 'raw and released by free, then the free may allow the memory formerly occupied by the reference to be used later by the garbage collector.

The cpointer-gcable? function returns #t for a cpointer generated via the _gcpointer type, while it generates #f for a cpointer generated via the _cpointer type.

value

_racket : ctype?

value

_scheme : ctype?

A type that can be used with any Racket object; it corresponds to the Scheme_Object* type of Racket’s C API (see Inside: Racket C API). It is useful only for libraries that are aware of Racket’s C API.

value

_fpointer : ctype?

Similar to _pointer, except that when _fpointer is used as the type for get-ffi-obj or ffi-obj-ref, then a level of indirection is skipped. Furthermore, for a C pointer value from get-ffi-obj or ffi-obj-ref using _fpointer, ptr-ref on the pointer as a _fpointer simply returns the pointer instead of dereferencing it. Like _pointer, _fpointer treats #f as NULL and vice versa.

A type generated by _cprocedure or _fun builds on _fpointer, and normally _cprocedure or _fun should be used instead of _fpointer.

procedure

(_or-null ctype) → ctype?

  ctype : ctype?
Creates a type that is like ctype, but #f is converted to NULL and vice versa. The given ctype must have the same C representation as _pointer, _gcpointer, or _fpointer.

procedure

(_gcable ctype) → ctype?

  ctype : ctype?
Creates a type that is like ctype, but whose base representation is like _gcpointer instead of _pointer. The given ctype must have a base representation like _pointer or _gcpointer (and in the later case, the result is the ctype).

  top  ← prev  up  next →