2.2 Base Foreign Types🔗ℹ
A generic pointer. On the C side, a generic pointer is represented as
an address with the same representation as
void*. On the Racket
side, a generic pointer is represented as a
pointer object. See
also
Foreign Pointers.
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.
Signed and unsigned integer
scalar types of specific bit widths
on the C side. All are represented as exact integers on the Racket
side, constrained to a range that fits in the unsigned or two’s
complement bit representation.
Signed and unsigned integer
scalar types of (in some cases)
platform-specific bit widths. For consistently, a
_t is
added to the end of C type names like
int to form a type name
like
int_t.
All are represented as exact integers on the Racket side, constrained
to a range that fits in the platform-specific C representation.
IEEE floating-point number
scalar types. On the C side, a
float_t is 8 bytes, and a
double_t is 16 bytes. On
the Racket side, both are represented as
flonums.
On the C side, both
wchar_t and
intwchar_t occupy
the same number of bytes. On the Racket side, a
wchar_t is
represented as a character, while a
intwchar_t is a
scalar type that is represented as an exact integer that fits
into 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,
#\�.
Boolean
scalar types. On the C side,
bool_t
corresponds to the C
bool type from
<stdbool.h>, while
boolint_t corresponds to
int (which is often used for a
boolean representation in C-based libraries). On the Racket side, both
are represented by boolean values when received from C, and and Racket
value is allowed when converting to C (where
#f is treated as
false and all other values are treated as true).
A type with no representation on the C side and a
(void)
representation on the Racket side. The
void_t type can only
be used for the result of a foreign procedure for foreign callback.
Types that are represented on the C side like
ptr_t, but that
are represented in Racket by conversion to and from strings, byte
strings, and paths—
or by
#f to represent a
NULL
pointer.
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.
A type that is represented on the C side like
ptr_t, but on
the Racket side by an arbitrary value. This type can only be used for
a procedure argument or result, and it will make sense only when
interacting with a foreign procedure that is specifically aware of the
Racket runtime system and cooperating with it.