# Foreign type specifiers

Here is a list of valid foreign type specifiers:

## scheme-object

An arbitrary Scheme data object (immediate or non-immediate).

## bool

As argument: any value (`#f` is false, anything else is true).

As result: anything different from 0 and the `NULL` pointer is `#t`.

## byte unsigned-byte

A byte.

## char unsigned-char

A character.

## short unsigned-short

A short integer number.

## int unsigned-int int32 unsigned-int32

An small integer number in fixnum range (at least 30 bit).

## integer unsigned-integer integer32 unsigned-integer32 integer64

Either a fixnum or a flonum in the range of a (unsigned) machine int or with 32/64 bit width.

## long unsigned-long

Either a fixnum or a flonum in the range of a (unsigned) machine long or with 32 bit width.

## float double

A floating-point number. If an exact integer is passed as an argument, then it is automatically converted to a float.

## number

A floating-point number. Similar to `double`, but when used as a result type, then either an exact integer or a floating-point number is returned, depending on whether the result fits into an exact integer or not.

## symbol

A symbol, which will be passed to foreign code as a zero-terminated string.

When declared as the result of foreign code, the result should be a string and a symbol with the same name will be interned in the symbol table (and returned to the caller).

## scheme-pointer

An untyped pointer to the contents of a non-immediate Scheme object (not allowed as return type). The value `#f` is also allowed and is passed as a `NULL` pointer.

Don't confuse this type with `(c-pointer ...)` which means something different (a machine-pointer object).

## nonnull-scheme-pointer

As `scheme-pointer`, but guaranteed not to be `#f`.

Don't confuse this type with `(nonnull-c-pointer ...)` which means something different (a machine-pointer object).

## c-pointer

An untyped operating-system pointer or a locative. The value `#f` is also allowed and is passed as a `NULL` pointer. If uses as the type of a return value, a `NULL` pointer will be returned as `#f`.

## nonnull-c-pointer

As `c-pointer`, but guaranteed not to be `#f/NULL`.

## blob

A blob object, passed as a pointer to its contents. Arguments of type `blob` may optionally be `#f`, which is passed as a NULL pointer.

This is not allowed as a return type.

## nonnull-blob

As `blob`, but guaranteed not to be `#f`.

## u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector

A SRFI-4 number-vector object, passed as a pointer to its contents.

These type specifiers are not allowed as return types.

## nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector

As `u8vector ...`, but guaranteed not to be `#f`.

## c-string

A C string (zero-terminated). The value `#f` is also allowed and is passed as a `NULL` pointer. If uses as the type of a return value, a `NULL` pointer will be returned as `#f`. Note that the string is copied (with a zero-byte appended) when passed as an argument to a foreign function. Also a return value of this type is copied into garbage collected memory.

## nonnull-c-string

As `c-string`, but guaranteed not to be `#f/NULL`.

## [nonnull-] c-string*

Similar to `[nonnull-] c-string`, but if used as a result-type, the pointer returned by the foreign code will be freed (using the C-libraries `free(1)`) after copying. This type specifier is not valid as a result type for callbacks defined with `define-external`.

## [nonnull-] unsigned-c-string[*]

Same as `c-string`, but maps to the `unsigned char *` C type.

## c-string-list

Expects a pointer to a list of C strings teminated by a `NULL` pointer and returns a list of strings.

Only valid as a result type of non-callback functions.

## c-string-list*

Similar to `c-string-list` but releases the storage of each string and the pointer array using `free(1)`.

## void

Specifies an undefined return value.

Not allowed as argument type.

## (const TYPE)

The foreign type `TYPE` with an additional `const` specifier.

## (enum NAME)

An enumeration type. Handled internally as an `integer`.

## (c-pointer TYPE)

An operating-system pointer or a locative to an object of `TYPE`.

## (nonnull-c-pointer TYPE)

As `(c-pointer TYPE)`, but guaranteed not to be `#f/NULL`.

## (ref TYPE)

A C++ reference type. Reference types are handled the same way as pointers inside Scheme code.

## (struct NAME)

A struct of the name `NAME`, which should be a string.

Structs cannot be directly passed as arguments to foreign function, neither can they be result values. Pointers to structs are allowed, though.

## (template TYPE ARGTYPE ...)

A C++ template type. For example `vector<int>` would be specified as `(template "vector" int)`.

Template types cannot be directly passed as arguments or returned as results.

## (union NAME)

A union of the name `NAME`, which should be a string.

Unions cannot be directly passed as arguments to foreign function, neither can they be result values. Pointers to unions are allowed, though.

## (instance CNAME SCHEMECLASS)

A pointer to a C++ class instance. `CNAME` should designate the name of the C++ class, and `SCHEMECLASS` should be the class that wraps the instance pointer. Normally `SCHEMECLASS` should be a subclass of `<c++-object>`.

## (instance-ref CNAME SCHEMECLASS)

A reference to a C++ class instance.

## (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])

A function pointer. `CALLCONV` specifies an optional calling convention and should be a string. The meaning of this string is entirely platform dependent. The value `#f` is also allowed and is passed as a `NULL` pointer.

## Mappings

Foreign types are mapped to C types in the following manner:

bool | int
[unsigned-]char | [unsigned] char
[unsigned-]short | [unsigned] short
[unsigned-]int | [unsigned] int
[unsigned-]integer | [unsigned] int
[unsigned-]long | [unsigned] long
float | float
double | double
number | double
[nonnull-]c-pointer | void *
[nonnull-]blob | unsigned char *
[nonnull-]u8vector | unsigned char *
[nonnull-]s8vector | char *
[nonnull-]u16vector | unsigned short *
[nonnull-]s16vector | short *
[nonnull-]u32vector | uint32_t *
[nonnull-]s32vector | int32_t *
[nonnull-]f32vector | float *
[nonnull-]f64vector | double *
[nonnull-]c-string | char *
[nonnull-]unsigned-c-string | unsigned char *
c-string-list | char **
symbol | char *
void | void
([nonnull-]c-pointer TYPE) | TYPE *
(enum NAME) | enum NAME
(struct NAME) | struct NAME
(ref TYPE) | TYPE &
(template T1 T2 ...) | T1<T2, ...>
(union NAME) | union NAME
(function RTYPE (ATYPE ...) [CALLCONV]) | [CALLCONV] RTYPE (*)(ATYPE, ...)
(instance CNAME SNAME) | CNAME *
(instance-ref CNAME SNAME) | CNAME &

Previous: Accessing external objects

Next: Embedding