► |  | 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

► | 3.4 | String Types

3.4.1 | Primitive String Types
3.4.2 | Fixed Auto-Converting String Types
3.4.3 | Variable Auto-Converting String Type
3.4.4 | Other String Types

On this page:

3.4.1`` Primitive String Types
_ string/ ucs-4
_ string/ utf-16
_ path
_ symbol
3.4.2`` Fixed Auto-Converting String Types
_ string/ utf-8
_ string/ latin-1
_ string/ locale
_ string*/ utf-8
_ string*/ latin-1
_ string*/ locale
3.4.3`` Variable Auto-Converting String Type
_ string
default-_ string-type
3.4.4`` Other String Types
_ file
_ bytes/ eof
_ string/ eof

top ← prev up next →

#### 3.4`` String Types

##### 3.4.1`` Primitive String Types

See also _bytes/nul-terminated and _bytes for converting between byte strings and C’s char* type.

> > value

> > _string/ucs-4 : ctype?

A type for UCS-4 format strings that include a nul terminator. As usual, the type treats #f as NULL and vice versa.

For the CS implementation of Racket, the conversion of a Racket string for the foreign side is a copy of the Racket representation, where the copy is managed by the garbage collector.

For the BC implementation of Racket, the conversion of a Racket string for the foreign side shares memory with the Racket string representation, since UCS-4 is the native representation format for those variants. The foreign pointer corresponds to the mzchar* type in Racket’s C API.

> > value

> > _string/utf-16 : ctype?

Unicode strings in UTF-16 format that include a nul terminator. As usual, the types treat #f as NULL and vice versa.

The conversion of a Racket string for the foreign side is a copy of the Racket representation (reencoded), where the copy is managed by the garbage collector.

> > value

> > _path : ctype?

Simple char* strings that are nul terminated, corresponding to Racket’s path or string. As usual, the type treats #f as NULL and vice versa.

For the BC implementation of Racket, the conversion of a Racket path for the foreign side shares memory with the Racket path representation. Otherwise (for the CS implementation or for Racket strings), conversion for the foreign side creates a copy that is managed by the garbage collector.

Beware that changing the current directory via current-directory does not change the OS-level current directory as seen by foreign library functions. Paths normally should be converted to absolute form using path->complete-path (which uses the current-directory parameter) before passing them to a foreign function.

> > value

> > _symbol : ctype?

Simple char* strings as Racket symbols (encoded in UTF-8 and nul terminated), intended as read-only for the foreign side. Return values using this type are interned as symbols.

For the CS implementation of Racket, the conversion of a Racket symbol for the foreign side is a copy of the Racket representation, where the copy is managed by the garbage collector.

For the BC implementation of Racket, the conversion of a Racket symbol for the foreign side shares memory with the Racket symbol representation, but points to the middle of the symbol’s allocated memory—so the string pointer must not be used across a garbage collection.

##### 3.4.2`` Fixed Auto-Converting String Types

> > value

> > _string/utf-8 : ctype?

> _string/latin-1 : ctype?
> _string/locale : ctype?

Types that correspond to (character) strings on the Racket side and char* strings on the C side. The bridge between the two requires a transformation on the content of the string. As usual, the types treat #f as NULL and vice versa.

> > value

> > _string*/utf-8 : ctype?

> _string*/latin-1 : ctype?
> _string*/locale : ctype?

Similar to _string/utf-8, etc., but accepting a wider range of values: Racket byte strings are allowed and passed as is, and Racket paths are converted using path->bytes.

##### 3.4.3`` Variable Auto-Converting String Type

The _string/ucs-4 type is rarely useful when interacting with foreign code, while using _bytes/nul-terminated is somewhat unnatural, since it forces Racket programmers to use byte strings. Using _string/utf-8, etc., meanwhile, may prematurely commit to a particular encoding of strings as bytes. The _string type supports conversion between Racket strings and char* strings using a parameter-determined conversion.

> > value

> > _string : ctype?

Expands to a use of the default-_string-type parameter. The parameter’s value is consulted when _string is evaluated, so the parameter should be set before any interface definition that uses _string.

Don’t use _string when you should use _path. Although C APIs typically represent paths as strings, and although the default _string (via default-_string-type) even implicitly converts Racket paths to strings, using _path ensures the proper encoding of strings as paths, which is not always UTF-8. See also _path for a caveat about relative paths.

> > parameter

> > (default-_string-type) → ctype?

> (default-_string-type type) → void?
> type : ctype?

A parameter that determines the current meaning of _string. It is initially set to _string*/utf-8. If you change it, do so before interfaces are defined.

##### 3.4.4`` Other String Types

> > value

> > _file : ctype?

Like _path, but when values go from Racket to C, cleanse-path is used on the given value. As an output value, it is identical to _path.

> > value

> > _bytes/eof : ctype?

Similar to the _bytes type, except that a foreign return value of NULL is translated to a Racket eof value.

> > value

> > _string/eof : ctype?

Similar to the _string type, except that a foreign return value of NULL is translated to a Racket eof value.
top ← prev up next →