6.2.3 Conversions between Prolog Arguments and C Types

The following table lists the possible values for the arguments in the predicate specification of foreign/[2,3]. The value declares which conversion between corresponding Prolog argument and C type will take place.

Prolog: +integer

C: SP_integer

The argument should be a number. It is converted to a C SP_integer and passed to the C function. If the number does not fit in a SP_integer, an exception is thrown.

Prolog: +float

C: double

The argument should be a number. It is converted to a C double and passed to the C function. If the number is a large integer that does not fit in a double, then an exception is thrown.

Prolog: +atom

C: SP_atom

The argument should be an atom. Its canonical representation is passed to the C function.

Prolog: +codes

C: char const *

The argument should be a code list. The C function will be passed the address of an array with the encoded string representation of these characters. The array is subject to reuse by other support functions, so if the value is going to be used on a more than temporary basis, then it must be moved elsewhere.

Prolog: +string

C: char const *

The argument should be an atom. The C function will be passed the address of an encoded string representing the characters of the atom. Please note: The C function must not overwrite the string.

Prolog: +address

C: void *

The value passed will be a void * pointer.

Prolog: +address(TypeName)

C: TypeName *

The value passed will be a TypeName * pointer.

Prolog: +term

C: SP_term_ref

The argument could be any term. The value passed will be the internal representation of the term.

Prolog: -integer

C: SP_integer *

The C function is passed a reference to an uninitialized SP_integer. The value returned will be converted to a Prolog integer.

Prolog: -float

C: double *

The C function is passed a reference to an uninitialized double. The value returned will be converted to a Prolog float. If the value returned is not finite, i.e. it is infinite or NaN, then an exception is thrown.

Prolog: -atom

C: SP_atom *

The C function is passed a reference to an uninitialized SP_atom. The value returned should be the canonical representation of a Prolog atom.

Prolog: -codes

C: char const **

The C function is passed the address of an uninitialized char *. The returned encoded string will be converted to a Prolog code list.

Prolog: -string

C: char const **

The C function is passed the address of an uninitialized char *. The returned encoded string will be converted to a Prolog atom. Prolog will copy the string to a safe place, so the memory occupied by the returned string may be reused during subsequent calls to foreign code.

Prolog: -address

C: void **

The C function is passed the address of an uninitialized void *.

Prolog: -address(TypeName)

C: TypeName **

The C function is passed the address of an uninitialized TypeName *.

Prolog: -term

C: SP_term_ref

The C function is passed a new SP_term_ref, and is expected to set its value to a suitable Prolog term. Prolog will try to unify the value with the actual argument.

Prolog: [-integer]

C: SP_integer F()

The C function should return an SP_integer. The value returned will be converted to a Prolog integer.

Prolog: [-float]

C: double F()

The C function should return a double. The value returned will be converted to a Prolog float. If the value returned is not finite, i.e. it is infinite or NaN, then an exception is thrown.

Prolog: [-atom]

C: SP_atom F()

The C function should return an SP_atom. The value returned must be the canonical representation of a Prolog atom.

Prolog: [-codes]

C: char const *F()

The C function should return a char *. The returned encoded string will be converted to a Prolog code list.

Prolog: [-string]

C: char const *F()

The C function should return a char *. The returned encoded string will be converted to a Prolog atom. Prolog will copy the string to a safe place, so the memory occupied by the returned string may be reused during subsequent calls to foreign code.

Prolog: [-address]

C: void *F()

The C function should return a void *, which will be converted to a Prolog integer.

Prolog: [-address(TypeName)]

C: TypeName *F()

The C function should return a TypeName *.

Prolog: [-term]

C: SP_term_ref F()

The C function should return an SP_term_ref. Prolog will try to unify its value with the actual argument.