12.3.2.2 Notes on C API bool return values

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.