Passing Atoms as Strings

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.