Chicken » Foreign type specifiers

## 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 unsigned-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).

`scheme-pointer` is typically used to get a pointer to the raw byte content of strings and blobs. But if you pass in a SRFI-4 vector, you will get a pointer to a blob object (not the blob's contents), which is almost certainly wrong. Instead, convert to a blob beforehand, or use a SRFI-4 specific type.

### 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`.

### pointer-vector

A vector of foreign pointer objects. `#f` is allowed and passed as a `NULL` pointer.

### nonnull-pointer-vector

As `pointer-vector`, 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 wrapped into a Scheme object instance. `CNAME` should designate the name of the C++ class, and `SCHEMECLASS` should be the class that wraps the instance pointer.

To use this, an extension will be required that provides an object-creation- and access-interface compatible to coops or tinyclos. Specifically, it should provide the following operations:

     (make SCHEMECLASS 'this POINTER)
     (slot-ref INSTANCE 'this)

### (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-]byte | [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-]pointer-vector | 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