Foreign type specifiers (historical revision 22456)

You are looking at historical revision 22456 of this page. It may differ significantly from its current revision.

manual

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.

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.

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.

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. Speecifically, it should provide the following operations:

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

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