Special attention is required when passing numbers. C‘promotes’any integral smaller than int to int. That is, the types char, short and int are all passed as int. In addition, on most 32-bit platforms int and long are the same. Up to version 4.0.5, only PL_INTEGER could be specified, which was taken from the stack as long. Such code fails when passing small integral types on machines where int is smaller than long. It is advised to use PL_SHORT, PL_INT or PL_LONG as appropriate. Similarly, C compilers promote float to double and therefore PL_FLOAT and PL_DOUBLE are synonyms.

The type identifiers are:

PL_VARIABLE none

No op. Used in arguments of PL_FUNCTOR.

PL_BOOL int

Unify the argument with true or false.

PL_ATOM atom_t

Unify the argument with an atom, as in PL_unify_atom().

PL_CHARS const char *

Unify the argument with an atom constructed from the C char *, as in PL_unify_atom_chars().

PL_NCHARS size_t, const char *

Unify the argument with an atom constructed from length and char* as in PL_unify_atom_nchars().

PL_UTF8_CHARS const char *

Create an atom from a UTF-8 string.

PL_UTF8_STRING const char *

Create a packed string object from a UTF-8 string.

PL_MBCHARS const char *

Create an atom from a multi-byte string in the current locale.

PL_MBCODES const char *

Create a list of character codes from a multi-byte string in the current locale.

PL_MBSTRING const char *

Create a packed string object from a multi-byte string in the current locale.

PL_NWCHARS size_t, const wchar_t *

Create an atom from a length and a wide character pointer.

PL_NWCODES size_t, const wchar_t *

Create a list of character codes from a length and a wide character pointer.

PL_NWSTRING size_t, const wchar_t *

Create a packed string object from a length and a wide character pointer.

PL_SHORT short

Unify the argument with an integer, as in PL_unify_integer(). As short is promoted to int, PL_SHORT is a synonym for PL_INT.

PL_INTEGER long

Unify the argument with an integer, as in PL_unify_integer().

PL_INT int

Unify the argument with an integer, as in PL_unify_integer().

PL_LONG long

Unify the argument with an integer, as in PL_unify_integer().

PL_INT64 int64_t

Unify the argument with a 64-bit integer, as in PL_unify_int64().

PL_INTPTR intptr_t

Unify the argument with an integer with the same width as a pointer. On most machines this is the same as PL_LONG. but on 64-bit MS-Windows pointers are 64 bits while longs are only 32 bits.

PL_DOUBLE double

Unify the argument with a float, as in PL_unify_float(). Note that, as the argument is passed using the C vararg conventions, a float must be casted to a double explicitly.

PL_FLOAT double

Unify the argument with a float, as in PL_unify_float().

PL_POINTER void *

Unify the argument with a pointer, as in PL_unify_pointer().

PL_STRING const char *

Unify the argument with a string object, as in PL_unify_string_chars().

PL_TERM term_t

Unify a subterm. Note this may be the return value of a PL_new_term_ref() call to get access to a variable.

PL_FUNCTOR functor_t, ...

Unify the argument with a compound term. This specification should be followed by exactly as many specifications as the number of arguments of the compound term.

PL_FUNCTOR_CHARS const char *name, int arity, ...

Create a functor from the given name and arity and then behave as PL_FUNCTOR.

PL_LIST int length, ...

Create a list of the indicated length. The remaining arguments contain the elements of the list.

For example, to unify an argument with the term language(dutch), the following skeleton may be used:

static functor_t FUNCTOR_language1;

static void
init_constants()
{ FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"),1);
}

foreign_t
pl_get_lang(term_t r)
{ return PL_unify_term(r,
                       PL_FUNCTOR, FUNCTOR_language1,
                           PL_CHARS, "dutch");
}

install_t
install()
{ PL_register_foreign("get_lang", 1, pl_get_lang, 0);
  init_constants();
}