SWI-Prolog -- API-function PL

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
      - Prolog exceptions in foreign code
        
        PL_raise_exception()
        
        PL_throw()
        
        PL_exception()
        
        PL_clear_exception()
- Packages

Availability:C-language interface function

term_t PL_exception(qid_t qid)

Return the pending exception. Exceptions may be raised by most of the API calls described in this chapter, a common possibility being resource_error exceptions. Some return type_error or domain_error exceptions. A call to Prolog using PL_next_solution() may return any exception, including those thrown by explicit calls to throw/1. If no exception is pending this function returns (term_t)0.

Normally qid should be 0. An explicit qid must be used after a call to PL_next_solution() that returns FALSE when the query was created using the PL_Q_PASS_EXCEPTION flag (see PL_open_query()).

Note that an API may only raise an exception when it fails; if the API call succeeds, the result of PL_exception(0) will be 0.^{230Provided no exception
was pending before calling the API function. As clients must deal with
exceptions immediately after an API call raises one, this can not happen
in a well behaved client.} The implementation of a foreign predicate should normally cleanup and return FALSE after an exception is raised (and typically also after an API call failed for logical reasons; see PL_unify() for an elaboration on this topic). If the call to Prolog is not the implementation of a foreign predicate, e.g., when the overall process control is in some other language, exceptions may be printed by calling print_message/2 and should be discarded by calling PL_clear_exception().