3.5 Pointer Types

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 3 | C Types

3.1 | Type Constructors
3.2 | Numeric Types
3.3 | Other Atomic Types
3.4 | String Types
3.5 | Pointer Types
3.6 | Function Types
3.7 | C Struct Types
3.8 | C Array Types
3.9 | C Union Types
3.10 | Enumerations and Masks

On this page:

_ pointer
_ gcpointer
_ racket
_ scheme
_ fpointer
_ or-null
_ gcable

top contents ← 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.

As a result type, 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. As an argument type, _pointer works for a reference to either GC-managed memory or not.

The equal? predicate equates C pointers (including pointers for _gcpointer and possibly containing an offset) when they refer to the same address—except for C pointers that are instances of structure types with the prop:cpointer property, in which case the equality rules of the relevant structure types apply.

> value _gcpointer : ctype?

The same as _pointer as an argument type, but as a result type, _gcpointer corresponds to a C pointer value that refers to memory managed by the garbage collector.

In the BC implementation of Racket, a _gcpointer result pointer can reference to memory that is not managed by the garbage collector, but 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 result type. See cpointer-gcable? for more information.

> 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). The _racket or _scheme type is useful only for libraries that are aware of Racket’s C API.

As a result type with a function type, _racket or _scheme permits multiple values, but multiple values are not allowed in combination with a true value for #:in-original-place? or #:async-apply in _cprocedure or _fun.

> 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 contents ← prev up next →