Most of the SWI-Prolog C-API consists of C functions that return a
Boolean result. Up to version 9.3.10, these functions are defined to
return int. Later versions define these functions to return
the bool. This type is provided by the standard header
stdbool.h and will be supported as a native type starting
with the C23 standard, which introduces the keywords false,
true and bool. SWI-Prolog.h
defines the constants FALSE and TRUE. These
constants are consistent with false, and true
and may be used interchangeably. Future versions will deprecate FALSE
and
TRUE. As of version 9.3.11 SWI-Prolog.h
includes
stdbool.h and thus provides the standard names.
The Boolean result true indicates success, while false
may indicate an error or logical failure. Which of the two
happened can be examined by calling PL_exception(0),
which returns a
term_t of value 0 if there was a logical failure. Otherwise
the returned term reference is a handle to the Prolog exception.
Typically there is no need to test whether or not there has been an
exception. Instead, the implementation of a foreign predicate can often
simply return false in case some API returned
false. Prolog will map this to logical failure or raise the
pending exception. The C API defines several groups of bool
functions that behave consistently. Note that errors which as the Prolog
term handle (term_t) not being a valid is not reported
through the API. If this is detected PL_api_error()
is called, which aborts the process with a diagnostic message. If not
detected, such errors lead to undefined behaviour (read:
arbitrary crashes or wrong behaviour now or later).
- PL_is_*()
- These are type checking functions. They have no side effects
and no error conditions. Returning
false implies the
argument is not of the tested type.
- PL_get_*()
- This group extracts C value from a Prolog term. If the term is not of
the expected type or the C value cannot represent the value the function
returns
false. No exception is raised.
- PL_get_*_ex()
- This group is similar to PL_get_*(), but raises a Prolog exception. The
exception is either an
instantiation_error in case the term
is unbound but should not be, a type_error in case the term
is of the wrong type or a representation_error in case the
C type cannot represent the Prolog value (e.g., a C
int while the Prolog integer is out of reach for this
type).
- PL_put_*()
- This group converts C data to a Prolog term. Such a function returning
false
always raises a resource_error, indicating that Prolog does
not have sufficient resources to store the result.
- PL_unify_*()
- This group unifies a Prolog term to a converted C value. Here, the
failure can be logical if the unification failed because the
term was already bound to some other value or the failure may be the
result of a resource error as with the PL_put_*() group.
