9.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.

Please note: here, the term `chars' refers to a code-list, rather than to a char-list.

Prolog: +integer

C: long

The argument should be a number. It is converted to a C long and passed to the C function.

Prolog: +float

C: double

The argument should be a number. It is converted to a C double and passed to the C function.

Prolog: +atom

C: SP_atom

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

Prolog: +chars

C: char *

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, it must be moved elsewhere.

Prolog: +string

C: char *

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

Prolog: +string(N) obsolescent

C: char *

The argument should be an atom. The encoded string representing the atom will be copied into a newly allocated buffer. The string will be truncated (at a wide character boundary) if it is longer than N bytes. The string will be blank padded on the right if it is shorter than N bytes. The C function will be passed the address of the buffer. The C function may overwrite the buffer, but should not assume that it remains valid after returning.

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: long *

The C function is passed a reference to an uninitialized long. 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.

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: -chars

C: char **

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

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: -string(N) obsolescent

C: char *

The C function is passed a reference to a character buffer large enough to store N bytes. The C function is expected to fill the buffer with an encoded string of N bytes (not NULL-terminated). This encoded string will be stripped of trailing blanks and converted to a Prolog atom.

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: long F()

The C function should return a long. 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.

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: [-chars]

C: char *F()

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

Prolog: [-string]

C: char *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: [-string(N)] obsolescent

C: char *F()

The C function should return a char *. The first N bytes of the encoded string (not necessarily NULL-terminated) will be copied and the copied string will be stripped of trailing blanks. The stripped string will be converted to a Prolog atom. C may reuse or destroy the string buffer during later calls.

Prolog: [-address]

C: void *F()

The C function should return a void *. (see Creating Prolog Terms), 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 a SP_term_ref. Prolog will try to unify its value with the actual argument.