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 as pointers to null-terminated character strings. Strings are always identical across different invocations of a program, so are the correct atom representation to use when writing to files or using interprogram communication. For other uses, atoms in the canonical form may be appropriate (see fli-ffp-dat-cat).
If, in a later release of Quintus Prolog, it is possible to call Prolog directly from FORTRAN or Pascal, it will additionally be possible to pass atoms as fixed-length, blank-padded strings (as when Prolog calls FORTRAN or Pascal).
Prolog: +string
C: char *x
The argument passed from the C function is a null-terminated character string. The foreign interface automatically converts the string to a Prolog atom, and passes it to the Prolog predicate.
Prolog: -string
C: char **x;
A pointer to a C string pointer 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 writes a pointer
to the string for that atom at the location supplied. The previous
contents of the location are destroyed. This string must not be
overwritten by the C function. 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.
See also fli-ffp-a2s for discussion of conversion between atoms and strings.