Passing Terms

The foreign function interface allows Prolog terms to be passed from C functions. Like most of the simple data types that may be passed to and from Prolog, terms to be passed can originate either in Prolog or in C (see fli-p2f-trm). Like terms in Prolog, terms that are passed to C are automatically made safe from damage by operations that might change their absolute position in Prolog memory, like stack shifting and garbage collection.

     Prolog:  +term
     C:       QP_term_ref

The argument passed from the C function is a QP_term_ref initialized to a Prolog term. If something other than a term reference is passed to Prolog, the results are undefined.

     Prolog:  -term
     C:       QP_term_ref

A QP_term_ref is passed to the foreign interface. When Prolog returns a solution, the foreign interface writes a reference to the Prolog term in the corresponding argument of the call into the QP_term_ref. The previous contents of the QP_term_ref are destroyed. Unlike the other passing types, there are no associated type errors when passing terms.

Note that the output term, as well as the input term is represented in the C code by a QP_term_ref. This contrasts with other output types, which are usually represented in C as pointers to the corresponding input type.