Next: Atoms in C, Up: Support Functions [Contents][Index]
Normally, C functions only have indirect access to Prolog terms
via SP_term_refs. C functions may receive arguments as
unconverted Prolog terms, in which case the actual arguments
received will have the type SP_term_ref
. Also, a C function may
return an unconverted Prolog term, in which case it must create an
SP_term_ref. Finally, any temporary Prolog terms created by
C code must be handled as SP_term_refs.
SP_term_refs are motivated by the fact that SICStus Prolog’s memory manager must have a means of reaching all live Prolog terms for memory management purposes, including such terms that are being manipulated by the user’s C code. Previous releases provided direct access to Prolog terms and the ability to tell the memory manager that a given memory address points to a Prolog term, but this approach was too low level and highly error-prone. The current design is modeled after and largely compatible with Quintus Prolog release 3.
SP_term_refs are created dynamically. At any given time, an
SP_term_ref has a value (a Prolog term, initially
[]
). This value can be examined, accessed, and updated by the
support functions described in this section.
A new SP_term_ref is created by calling SP_new_term_ref()
.
An SP_term_ref can be assigned the value of another SP_term_ref
by calling SP_put_term()
.
It is important to understand the rules governing the scope of SP_term_refs, and the terms they hold, in conjunction with calls from Prolog to C and vice versa. This is explained in Finding Multiple Solutions of a Call.