The foreign function interface allows Prolog atoms to be passed from C functions to Prolog either in a canonical form as unsigned integers, or as pointers to character strings.
This section describes passing atoms in canonical form. For each
Prolog atom there is a single canonical representation. Programs can
rely on the property that identical atoms have identical canonical
representations. Note, however, that the canonical form of an atom is
not necessarily identical across different invocations of the program.
This means that canonical atom representations should not be used in
files or interprogram communication. For these purposes strings
should be used (see fli-ffp-a2s-str). Foreign functions can
store canonical atoms in data structures, pass them around, access
their strings using QP_string_from_atom() and pass them back to
Prolog, but they should not attempt any other operations on them.
Prolog: +atom
C: QP_atom x;
The QP_atom must be a valid Prolog
atom, otherwise the function attempting to pass the atom parameter
(QP_query() or QP_open_query()) will return QP_ERROR.
The C QP_atom is passed to Prolog, where it will
appear as a normal Prolog atom. Atoms can be converted to strings
using the functions QP_string_from_atom() or
QP_atom_from_padded_string() (see fli-p2f-atm-a2s).
Prolog: -atom
C: QP_atom *x
A pointer to a C QP_atom is passed to the foreign interface.
When Prolog returns a solution, a Prolog atom is expected in the
corresponding argument of the call. This atom might be one obtained
from Prolog, or one generated through the function
QP_atom_from_string() or QP_atom_from_padded_string() (see
fli-p2f-atm-a2s). The foreign interface simply writes
that atom at the location supplied. The previous contents
of the location are destroyed. If the Prolog call does not
return an atom in the appropriate position, a type error is raised
and the contents of the location is unchanged.
Also see fli-ffp-a2s for discussion of conversion between atoms and strings.