12.3.2 Other foreign interface types

atom_t

An atom in Prolog's internal representation. Atoms are pointers to an opaque structure. They are a unique representation for represented text, which implies that atom A represents the same text as atom B if and only if A and B are the same pointer.

Atoms are the central representation for textual constants in Prolog. The transformation of a character string C to an atom implies a hash-table lookup. If the same atom is needed often, it is advised to store its reference in a global variable to avoid repeated lookup.

functor_t

A functor is the internal representation of a name/arity pair. They are used to find the name and arity of a compound term as well as to construct new compound terms. Like atoms they live for the whole Prolog session and are unique.

predicate_t

Handle to a Prolog predicate. Predicate handles live forever (although they can lose their definition).

qid_t

Query identifier. Used by PL_open_query(), PL_next_solution() and PL_close_query() to handle backtracking from C.

fid_t

Frame identifier. Used by PL_open_foreign_frame() and PL_close_foreign_frame().

module_t

A module is a unique handle to a Prolog module. Modules are used only to call predicates in a specific module.

foreign_t

Return type for a C function implementing a Prolog predicate.

control_t

Passed as additional argument to non-deterministic foreign functions. See PL_retry*() and PL_foreign_context*().

install_t

Type for the install() and uninstall() functions of shared or dynamic link libraries. See section 12.2.3.

int64_t

Actually part of the C99 standard rather than Prolog. As of version 5.5.6, Prolog integers are 64-bit on all hardware. The C99 type int64_t is defined in the stdint.h standard header and provides platform-independent 64-bit integers. Portable code accessing Prolog should use this type to exchange integer values. Please note that PL_get_long() can return FALSE on Prolog integers that cannot be represented as a C long. Robust code should not assume any of the integer fetching functions to succeed, even if the Prolog term is known to be an integer.

12.3.2.1 PL_ARITY_AS_SIZE

As of SWI-Prolog 7.3.12, the arity of terms has changed from int to size_t. To deal with this transition, all affecting functions have two versions, where the old name exchanges the arity as int and a new function with name *_sz() exchanges the arity as size_t. If the C macro PL_ARITY_AS_SIZE is defined before loading SWI-Prolog.h, macros are put in place that map the old names to the new functions. Without precautions, the old code is compatible, but the following warning is printed when compiling:

#warning "Term arity has changed from int to size_t."
#warning "Please update your code and use #define PL_ARITY_AS_SIZE 1."

To make the code compile silently again, include SWI-Prolog.h as below and change the types you use to represent arity from int to size_t. Please be aware that size_t is unsigned.

#define PL_ARITY_AS_SIZE
#include <SWI-Prolog.h>