Passing Atoms in Canonical Form

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.