Passing Atoms as Strings between Prolog and C

This section describes passing atoms as pointers to null-terminated character strings. This is the way to pass atoms as strings between Prolog and C. For FORTRAN and Pascal, the specification of string arguments is different than for C; see fli-p2f-atm-spf.

     Prolog:  +string
     C:       char *x
     Pascal:  Not supported
     FORTRAN: Not supported
     

The argument must be instantiated to an atom, otherwise the call will signal an error. A pointer to a null-terminated string of characters is passed to the C function. This string must not be overwritten by the C function.

     Prolog:  -string
     C:       char **x;
              *x = ...
     Pascal:  Not supported
     FORTRAN: Not supported
     

A pointer to a character pointer is passed to the C function. It is assumed that C will overwrite this character pointer with the result it wishes to return. This result should be a pointer to a null-terminated string of characters. When the C function returns, the atom that has the printed representation specified by the string is unified with the corresponding argument of the Prolog call. The argument can be of any type; if it cannot be unified with the returned atom, then the call fails. If the C function does not overwrite the character pointer, then the result is undefined.

Prolog copies the string if required, so that it is not necessary for the C program to worry about retaining it. Beware, however, that the string must not be an auto, because in this case its storage may be reclaimed after the foreign function exits but before Prolog has managed to copy it.

     Prolog:  [-string]
     C        char *f(...)
                {
                  char *x;
                  return x;
                }
     Pascal:  Not supported
     FORTRAN: Not supported
     

No argument is passed to C. The return value from the C function is assumed to be a character pointer pointing to a null-terminated string of characters. The atom that has the printed representation specified by the string is unified with the corresponding argument of the Prolog call. The argument can be of any type; if it cannot be unified with the returned atom, the call fails.

Prolog copies the string if required, so that it is not necessary for the C program to worry about retaining it. Beware, however, that the string must not be an auto, because in this case its storage may be reclaimed after the foreign function exits but before Prolog has managed to copy it.