3.2 Base Foreign Types🔗ℹ

When an address is converted from C to Racket, then ptr_t produces a pointer object that references memory (assumed to be) not managed by Racket’s garbage collector. The ptr_t/gcable type implies that a pointer converted from C should be treated as (potentially) managed by Racket/s garbage collector. In both cases, conversion from Racket to C allows any pointer object.

The void_t* type is equivalent to ptr_t, and the void_t*/gcable type is equivalent to ptr_t/gcable.

All are represented as exact integers on the Racket side, constrained to a range that fits in the platform-specific C representation.

The range of wchar_t on the C side may include integers that do not correspond to a Racket character, and it may omit values that do correspond to a Racket character. The Racket representation of a wchar_t is constrained to characters that fit in the C representation, and values from C that are are not representable as Racket characters are converted to the Unicode replacement character, #\uFFFD.

For Racket-to-C conversion, the string_t type converts a Racket string to a null-terminated byte string and passes the address of the start of the byte string to the C side. The string_utf16_t type similarly converts a Racket string to a UTF-16 sequence with a two-byte null terminator. The bytes_t type similarly copies a Racket byte string to add a null terminator, while bytes_ptr_t passes the start of a Racket byte string as-is, without adding a terminator (and where mutation of pointer content on the C side is reflected as changes to the byte string content). The path_t is like string_t, but for paths in the sense of path-for-some-system?, and Racket to C conversion adjusts relative paths using path->complete-path. All of these types convert #f on the Racket side to NULL on the C side.

When converting from C to Racket, a non-NULL pointer received from C is treated as a reference to a null-terminated C string (with an aligned, two-byte terminator in the case of string_utf16_t), and a fresh Racket byte string is created to hold the content up to the null terminator. The string_t, string_utf16_t, and path_t types then convert that byte string to a string or path. A NULL from C is converted to #f for Racket.

The flvector_ptr_t type does not support C-to-Racket conversion. Attempting a conversion in that direction raises an exception.

Added in version 1.2 of package ffi2-lib.