## 9.6 The Foreign Include File

### 9.6.1 Argument Passing and Control

If Prolog encounters a foreign predicate at run time it will call a function specified in the predicate definition of the foreign predicate. The arguments 1, ... , <arity> pass the Prolog arguments to the goal as Prolog terms. Foreign functions should be declared of type `foreign_t`. Deterministic foreign functions have two alternatives to return control back to Prolog:

(return) foreign_t PL_succeed()
  Succeed deterministically. PL_succeed is defined as `return `TRUE``.
(return) foreign_t PL_fail()
  Fail and start Prolog backtracking. PL_fail is defined as `return `FALSE``.

#### 9.6.1.1 Non-deterministic Foreign Predicates

By default foreign predicates are deterministic. Using the `PL_FA_NONDETERMINISTIC` attribute (see PL_register_foreign()) it is possible to register a predicate as a non-deterministic predicate. Writing non-deterministic foreign predicates is slightly more complicated as the foreign function needs context information for generating the next solution. Note that the same foreign function should be prepared to be simultaneously active in more than one goal. Suppose the natural_number_below_n/2 is a non-deterministic foreign predicate, backtracking over all natural numbers lower than the first argument. Now consider the following predicate:

    quotient_below_n(Q, N) :-
            natural_number_below_n(N, N1),
            natural_number_below_n(N, N2),
            Q =:= N1 / N2, !.

In this predicate the function natural_number_below_n/2 simultaneously generates solutions for both its invocations.

Non-deterministic foreign functions should be prepared to handle three different calls from Prolog:

- Initial call (`PL_FIRST_CALL`)
  Prolog has just created a frame for the foreign function and asks it to produce the first answer.
- Redo call (`PL_REDO`)
  The previous invocation of the foreign function associated with the current goal indicated it was possible to backtrack. The foreign function should produce the next solution.
- Terminate call (`PL_CUTTED`)
  The choice point left by the foreign function has been destroyed by a cut. The foreign function is given the opportunity to clean the environment.

Both the context information and the type of call is provided by an argument of type `control_t` appended to the argument list for deterministic foreign functions. The macro PL_foreign_control() extracts the type of call from the control argument. The foreign function can pass a context handle using the `PL_retry*()` macros and extract the handle from the extra argument using the `PL_foreign_context*()` macro.

(return) foreign_t PL_retry(long)
  The foreign function succeeds while leaving a choice point. On backtracking over this goal the foreign function will be called again, but the control argument now indicates it is a `Redo' call and the macro PL_foreign_context() returns the handle passed via PL_retry(). This handle is a 30 bits signed value (two bits are used for status indication). Defined as `return _PL_retry(n)`. See also PL_succeed().
(return) foreign_t PL_retry_address(void *)
  As PL_retry(), but ensures an address as returned by malloc() is correctly recovered by PL_foreign_context_address(). Defined as `return _PL_retry_address(n)`. See also PL_succeed().
int PL_foreign_control(control_t)
  Extracts the type of call from the control argument. The return values are described above. Note that the function should be prepared to handle the `PL_CUTTED` case and should be aware that the other arguments are not valid in this case.
long PL_foreign_context(control_t)
  Extracts the context from the context argument. In the call type is `PL_FIRST_CALL` the context value is 0L. Otherwise it is the value returned by the last PL_retry() associated with this goal (both if the call type is `PL_REDO` as `PL_CUTTED`).
void * PL_foreign_context_address(control_t)
  Extracts an address as passed in by PL_retry_address().

Note: If a non-deterministic foreign function returns using PL_succeed or PL_fail, Prolog assumes the foreign function has cleaned its environment. No call with control argument `PL_CUTTED` will follow.

The code of figure 8 shows a skeleton for a non-deterministic foreign predicate definition.

    typedef struct                  /* define a context structure */
    { ...
    } context;

    foreign_t
    my_function(term_t a0, term_t a1, control_t handle)
    { struct context * ctxt;

      switch( PL_foreign_control(handle) )
      { case PL_FIRST_CALL:
            ctxt = malloc(sizeof(struct context));
            ...
            PL_retry_address(ctxt);
        case PL_REDO:
            ctxt = PL_foreign_context_address(handle);
            ...
            PL_retry_address(ctxt);
        case PL_CUTTED:
            ctxt = PL_foreign_context_address(handle);
            ...
            free(ctxt);
            PL_succeed;
      }
    }

Figure 8 : Skeleton for non-deterministic foreign functions

### 9.6.2 Atoms and functors

The following functions provide for communication using atoms and functors.

atom_t PL_new_atom(const char *)
  Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced (see section 9.6.2.1).
const char* PL_atom_chars(atom_t atom)
  Return a C-string for the text represented by the given atom. The returned text will not be changed by Prolog. It is not allowed to modify the contents, not even `temporary' as the string may reside in read-only memory. The returned string becomes invalid if the atom is garbage-collected (see section 9.6.2.1). Foreign functions that require the text from an atom passed in a `term_t` normally use PL_get_atom_chars() or PL_get_atom_nchars().
functor_t PL_new_functor(atom_t name, int arity)
  Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session.
atom_t PL_functor_name(functor_t f)
  Return an atom representing the name of the given functor.
int PL_functor_arity(functor_t f)
  Return the arity of the given functor.

#### 9.6.2.1 Atoms and atom-garbage collection

With the introduction of atom-garbage collection in version 3.3.0, atoms no longer live as long as the process. Instead, their lifetime is guaranteed only as long as they are referenced. In the single-threaded version, atom garbage collections are only invoked at the call-port. In the multi-threaded version (see section 8), they appear asynchronously, except for the invoking thread.

For dealing with atom garbage collection, two additional functions are provided:

void PL_register_atom(atom_t atom)
  Increment the reference count of the atom by one. PL_new_atom() performs this automatically, returning an atom with a reference count of at least one.78Otherwise asynchronous atom garbage collection might destroy the atom before it is used.
void PL_unregister_atom(atom_t atom)
  Decrement the reference count of the atom. If the reference-count drops below zero, an assertion error is raised.

Please note that the following two calls are different with respect to atom garbage collection:

    PL_unify_atom_chars(t, "text");
    PL_unify_atom(t, PL_new_atom("text"));

The latter increments the reference count of the atom `text`, which effectively ensures the atom will never be collected. It is advised to use the *_chars() or *_nchars() functions whenever applicable.

### 9.6.3 Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type `term_t`, an opaque handle to a Prolog term. Three groups of functions are available for the analysis of terms. The first just validates the type, like the Prolog predicates var/1, atom/1, etc and are called `PL_is_*()`. The second group attempts to translate the argument into a C primitive type. These predicates take a `term_t` and a pointer to the appropriate C-type and return `TRUE` or `FALSE` depending on successful or unsuccessful translation. If the translation fails, the pointed-to data is never modified.

#### 9.6.3.1 Testing the type of a term

int PL_term_type(term_t)
  Obtain the type of a term, which should be a term returned by one of the other interface predicates or passed as an argument. The function returns the type of the Prolog term. The type identifiers are listed below. Note that the extraction functions `PL_ge_t*()` also validate the type and thus the two sections below are equivalent.

              if ( PL_is_atom(t) )
              { char *s;

                PL_get_atom_chars(t, &s);
                ...;
              }

      or

              char *s;
              if ( PL_get_atom_chars(t, &s) )
              { ...;
              }

  `PL_VARIABLE` | An unbound variable. The value of term as such is a unique identifier for the variable.
  `PL_ATOM` | A Prolog atom.
  `PL_STRING` | A Prolog string.
  `PL_INTEGER` | A Prolog integer.
  `PL_FLOAT` | A Prolog floating point number.
  `PL_TERM` | A compound term. Note that a list is a compound term ./2 .

The functions PL_is_<type> are an alternative to PL_term_type(). The test `PL_is_variable(term)` is equivalent to `PL_term_type(term) == PL_VARIABLE`, but the first is considerably faster. On the other hand, using a switch over PL_term_type() is faster and more readable then using an if-then-else using the functions below. All these functions return either `TRUE` or `FALSE`.

int PL_is_variable(term_t)
  Returns non-zero if term is a variable.
int PL_is_ground(term_t)
  Returns non-zero if term is a ground term. See also ground/1. This function is cycle-safe.
int PL_is_atom(term_t)
  Returns non-zero if term is an atom.
int PL_is_string(term_t)
  Returns non-zero if term is a string.
int PL_is_integer(term_t)
  Returns non-zero if term is an integer.
int PL_is_float(term_t)
  Returns non-zero if term is a float.
int PL_is_compound(term_t)
  Returns non-zero if term is a compound term.
int PL_is_functor(term_t, functor_t)
  Returns non-zero if term is compound and its functor is functor. This test is equivalent to PL_get_functor(), followed by testing the functor, but easier to write and faster.
int PL_is_list(term_t)
  Returns non-zero if term is a compound term with functor ./2 or the atom `[]`.
int PL_is_atomic(term_t)
  Returns non-zero if term is atomic (not variable or compound).
int PL_is_number(term_t)
  Returns non-zero if term is an integer or float.
int PL_is_acyclic(term_t)
  Returns non-zero if term is acyclic (i.e. a finite tree).

#### 9.6.3.2 Reading data from a term

The functions `PL_get_*()` read information from a Prolog term. Most of them take two arguments. The first is the input term and the second is a pointer to the output value or a term-reference.

int PL_get_atom(term_t +t, atom_t *a)
  If t is an atom, store the unique atom identifier over a. See also PL_atom_chars() and PL_new_atom(). If there is no need to access the data (characters) of an atom, it is advised to manipulate atoms using their handle. As the atom is referenced by t, it will live at least as long as t does. If longer live-time is required, the atom should be locked using PL_register_atom().
int PL_get_atom_chars(term_t +t, char **s)
  If t is an atom, store a pointer to a 0-terminated C-string in s. It is explicitly not allowed to modify the contents of this string. Some built-in atoms may have the string allocated in read-only memory, so `temporary manipulation' can cause an error.
int PL_get_string_chars(term_t +t, char **s, int *len)
  If t is a string object, store a pointer to a 0-terminated C-string in s and the length of the string in len. Note that this pointer is invalidated by backtracking, garbage-collection and stack-shifts, so generally the only save operations are to pass it immediately to a C-function that doesn't involve Prolog.
int PL_get_chars(term_t +t, char **s, unsigned flags)
  Convert the argument term t to a 0-terminated C-string. flags is a bitwise disjunction from two groups of constants. The first specifies which term-types should converted and the second how the argument is stored. Below is a specification of these constants. `BUF_RING` implies, if the data is not static (as from an atom), the data is copied to the next buffer from a ring of 16 buffers. This is a convenient way of converting multiple arguments passed to a foreign predicate to C-strings. If BUF_MALLOC is used, the data must be freed using PL_free() when not needed any longer.

  With the introduction of wide-characters (see section 2.17.1), not all atoms can be converted into a `char*`. This function fails if t is of the wrong type, but also if the text cannot be represented. See the `REP_*` flags below for details.

  `CVT_ATOM` | Convert if term is an atom
  `CVT_STRING` | Convert if term is a string
  `CVT_LIST` | Convert if term is a list of integers between 1 and 255
  `CVT_INTEGER` | Convert if term is an integer (using `%d`)
  `CVT_FLOAT` | Convert if term is a float (using `%f`)
  `CVT_NUMBER` | Convert if term is a integer or float
  `CVT_ATOMIC` | Convert if term is atomic
  `CVT_VARIABLE` | Convert variable to print-name
  `CVT_WRITE` | Convert any term that is not converted by any of the other flags using write/1. If no `BUF_*` is provided, `BUF_RING` is implied.
  `CVT_ALL` | Convert if term is any of the above, except for `CVT_VARIABLE` and `CVT_WRITE`
  `CVT_EXCEPTION` | If conversion fails due to a type error, raise a Prolog type error exception in addition to failure
  `BUF_DISCARDABLE` | Data must copied immediately
  `BUF_RING` | Data is stored in a ring of buffers
  `BUF_MALLOC` | Data is copied to a new buffer returned by PL_malloc(3). When no longer needed the user must call PL_free() on the data.
  `REP_ISO_LATIN_1` | (0, default). Text is in ISO Latin-1 encoding and the call fails if text cannot be represented.
  `REP_UTF8` | Convert the text to a UTF-8 string. This works for all text.
  `REP_MB` | Convert to default locale-defined 8-bit string. Success depends on the locale. Conversion is done using the wcrtomb() C-library function.

int PL_get_list_chars(+term_t l, char **s, unsigned flags)
  Same as `PL_get_chars(l, s, CVT_LIST|flags)`, provided flags contains no of the `CVT_*` flags.
int PL_get_integer(+term_t t, int *i)
  If t is a Prolog integer, assign its value over i. On 32-bit machines, this is the same as PL_get_long(), but avoids a warning from the compiler. See also PL_get_long().
int PL_get_long(term_t +t, long *i)
  If t is a Prolog integer that can be represented as a long, assign its value over i. If t is an integer that cannot be represented by a C long, this function returns `FALSE`. If t is a floating point number that can be represented as a long, this function succeeds as well. See also PL_get_int64()
int PL_get_int64(term_t +t, int64_t *i)
  If t is a Prolog integer or float that can be represented as a `int64_t`, assign its value over i. Currently all Prolog integers can be represented using this type, but this might change if SWI-Prolog introduces unbounded integers.
int PL_get_bool(term_t +t, int *val)
  If t has the value `true` or `false`, set val to the C constant `TRUE` or `FALSE` and return success. otherwise return failure.
int PL_get_pointer(term_t +t, void **ptr)
  In the current system, pointers are represented by Prolog integers, but need some manipulation to make sure they do not get truncated due to the limited Prolog integer range. PL_put_pointer()/PL_get_pointer() guarantees pointers in the range of malloc() are handled without truncating.
int PL_get_float(term_t +t, double *f)
  If t is a float or integer, its value is assigned over f.
int PL_get_functor(term_t +t, functor_t *f)
  If t is compound or an atom, the Prolog representation of the name-arity pair will be assigned over f. See also PL_get_name_arity() and PL_is_functor().
int PL_get_name_arity(term_t +t, atom_t *name, int *arity)
  If t is compound or an atom, the functor-name will be assigned over name and the arity over arity. See also PL_get_functor() and PL_is_functor().
int PL_get_module(term_t +t, module_t *module)
  If t is an atom, the system will lookup or create the corresponding module and assign an opaque pointer to it over module,.
int PL_get_arg(int index, term_t +t, term_t -a)
  If t is compound and index is between 1 and arity (including), assign a with a term-reference to the argument.
int _PL_get_arg(int index, term_t +t, term_t -a)
  Same as PL_get_arg(), but no checking is performed, nor whether t is actually a term, nor whether index is a valid argument-index.

#### 9.6.3.3 Exchanging text using length and string

All internal text-representation of SWI-Prolog is represented using `char *` plus length and allow for 0-bytes in them. The foreign library supports this by implementing a *_nchars() function for each applicable *_chars() function. Below we briefly present the signatures of these functions. For full documentation consult the *_chars() function.

int PL_get_atom_nchars(term_t t, size_t *len, char **s)
  See PL_get_atom_chars().
int PL_get_list_nchars(term_t t, size_t *len, char **s)
  See PL_get_list_chars().
int PL_get_nchars(term_t t, size_t *len, char **s, unsigned int flags)
  See PL_get_chars().
int PL_put_atom_nchars(term_t t, size_t len, const char *s)
  See PL_put_atom_chars().
int PL_put_string_nchars(term_t t, size_t len, const char *s)
  See PL_put_string_chars().
int PL_put_list_ncodes(term_t t, size_t len, const char *s)
  See PL_put_list_codes().
int PL_put_list_nchars(term_t t, size_t len, const char *s)
  See PL_put_list_chars().
int PL_unify_atom_nchars(term_t t, size_t len, const char *s)
  See PL_unify_atom_chars().
int PL_unify_string_nchars(term_t t, size_t len, const char *s)
  See PL_unify_string_chars().
int PL_unify_list_ncodes(term_t t, size_t len, const char *s)
  See PL_unify_codes().
int PL_unify_list_nchars(term_t t, size_t len, const char *s)
  See PL_unify_list_chars().

In addition, the following functions are available for creating and inspecting atoms:

atom_t PL_new_atom_nchars(size_t len, const char *s)
  Create a new atom as PL_new_atom(), but from length and characters.
const char * PL_atom_nchars(atom_t a, size_t *len)
  Extract text and length of an atom.

#### 9.6.3.4 Wide character versions

Support for exchange of wide character strings is still under consideration. The functions dealing with 8-bit character strings return failure when operating on a wide character atom or Prolog string object. The functions below can extract and unify both 8-bit and wide atoms and string objects. Wide character strings are represented as C arrays of objects of the type `pl_wchar_t`, which is guaranteed to be the same as `wchar_t` on platforms supporting this type. For example, on MS-Windows, this represents 16-bit UCS2 characters, while using the GNU C library (glibc) this represents 32-bit UCS4 characters.

atom_t PL_new_atom_wchars(size_t len, const pl_wchar_t *s)
  Create atom from wide-character string as PL_new_atom_nchars() does for ISO-Latin-1 strings. If s only contains ISO-Latin-1 characters a normal byte-array atom is created.
pl_wchar_t* PL_atom_wchars(atom_t atom, int *len)
  Extract characters from a wide-character atom. Fails (returns `NULL`) if atom is not a wide-character atom. This is the wide-character version of PL_atom_nchars(). Note that only one of these functions succeeds on a particular atom. Especially, after creating an atom with PL_new_atom_wchars(), extracting the text using PL_atom_wchars() will fail if the atom only contains ISO-Latin-1 characters.
int PL_get_wchars(term_t t, size_t *len, pl_wchar_t **s, unsigned flags)
  Wide-character version of PL_get_chars(). The flags argument is the same as for PL_get_chars().
int PL_unify_wchars(term_t t, int type, size_t len, const pl_wchar_t *s)
  Unify t with a textual representation of the C wide character array s. The argtype argument defines the Prolog representation and is one of `PL_ATOM`, `PL_STRING`, `PL_CODE_LIST` or `PL_CHAR_LIST`.
int PL_unify_wchars_diff(term_t +t, term_t -tail, int type, size_t len, const pl_wchar_t *s)
  Difference list version of PL_unify_wchars(), only supporting the types `PL_CODE_LIST` and `PL_CHAR_LIST`. It serves two purposes. It allows for returning very long lists from data read from a stream without the need for a resizing buffer in C. Also, the use of difference lists is often practical for further processing in Prolog. Examples can be found in `packages/clib/readutil.c` from the source distribution.

#### 9.6.3.5 Reading a list

The functions from this section are intended to read a Prolog list from C. Suppose we expect a list of atoms, the following code will print the atoms, each on a line:

    foreign_t
    pl_write_atoms(term_t l)
    { term_t head = PL_new_term_ref();      /* variable for the elements */
      term_t list = PL_copy_term_ref(l);    /* copy as we need to write */

      while( PL_get_list(list, head, list) )
      { char *s;

        if ( PL_get_atom_chars(head, &s) )
          Sprintf("%s\n", s);
        else
          PL_fail;
      }

      return PL_get_nil(list);              /* test end for [] */
    }

int PL_get_list(term_t +l, term_t -h, term_t -t)
  If l is a list and not `[]` assign a term-reference to the head to h and to the tail to t.
int PL_get_head(term_t +l, term_t -h)
  If l is a list and not `[]` assign a term-reference to the head to h.
int PL_get_tail(term_t +l, term_t -t)
  If l is a list and not `[]` assign a term-reference to the tail to t.
int PL_get_nil(term_t +l)
  Succeeds if represents the atom `[]`.

#### 9.6.3.6 An example: defining write/1 in C

Figure 9 shows a simplified definition of write/1 to illustrate the described functions. This simplified version does not deal with operators. It is called display/1, because it mimics closely the behaviour of this Edinburgh predicate.

    foreign_t
    pl_display(term_t t)
    { functor_t functor;
      int arity, len, n;
      char *s;

      switch( PL_term_type(t) )
      { case PL_VARIABLE:
        case PL_ATOM:
        case PL_INTEGER:
        case PL_FLOAT:
          PL_get_chars(t, &s, CVT_ALL);
          Sprintf("%s", s);
          break;
        case PL_STRING:
          PL_get_string_chars(t, &s, &len);
          Sprintf("\"%s\"", s);
          break;
        case PL_TERM:
        { term_t a = PL_new_term_ref();

          PL_get_name_arity(t, &name, &arity);
          Sprintf("%s(", PL_atom_chars(name));
          for(n=1; n<=arity; n++)
          { PL_get_arg(n, t, a);
            if ( n > 1 )
              Sprintf(", ");
            pl_display(a);
          }
          Sprintf(")");
          break;
        default:
          PL_fail;                          /* should not happen */
      }

      PL_succeed;
    }

Figure 9 : A Foreign definition of display/1

### 9.6.4 Constructing Terms

Terms can be constructed using functions from the `PL_put_*()` and `PL_cons_*()` families. This approach builds the term `inside-out', starting at the leaves and subsequently creating compound terms. Alternatively, terms may be created `top-down', first creating a compound holding only variables and subsequently unifying the arguments. This section discusses functions for the first approach. This approach is generally used for creating arguments for PL_call() and PL_open_query.

void PL_put_variable(term_t -t)
  Put a fresh variable in the term. The new variable lives on the global stack. Note that the initial variable lives on the local stack and is lost after a write to the term-references. After using this function, the variable will continue to live.
void PL_put_atom(term_t -t, atom_t a)
  Put an atom in the term reference from a handle. See also PL_new_atom() and PL_atom_chars().
void PL_put_atom_chars(term_t -t, const char *chars)
  Put an atom in the term-reference constructed from the 0-terminated string. The string itself will never be referenced by Prolog after this function.
void PL_put_string_chars(term_t -t, const char *chars)
  Put a zero-terminated string in the term-reference. The data will be copied. See also PL_put_string_nchars().
void PL_put_string_nchars(term_t -t, size_t len, const char *chars)

  Put a string, represented by a length/start pointer pair in the term-reference. The data will be copied. This interface can deal with 0-bytes in the string. See also section 9.6.19.

void PL_put_list_chars(term_t -t, const char *chars)
  Put a list of ASCII values in the term-reference.
void PL_put_integer(term_t -t, long i)
  Put a Prolog integer in the term reference.
void PL_put_int64(term_t -t, int64_t i)
  Put a Prolog integer in the term reference.
void PL_put_pointer(term_t -t, void *ptr)
  Put a Prolog integer in the term-reference. Provided ptr is in the `malloc()-area', PL_get_pointer() will get the pointer back.
void PL_put_float(term_t -t, double f)
  Put a floating-point value in the term-reference.
void PL_put_functor(term_t -t, functor_t functor)
  Create a new compound term from functor and bind t to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the `PL_unify_*()` functions or use PL_cons_functor().
void PL_put_list(term_t -l)
  Same as `PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2))`.
void PL_put_nil(term_t -l)
  Same as `PL_put_atom_chars("[]")`.
void PL_put_term(term_t -t1, term_t +t2)
  Make t1 point to the same term as t2.
void PL_cons_functor(term_t -h, functor_t f, ...)
  Create a term, whose arguments are filled from variable argument list holding the same number of term_t objects as the arity of the functor. To create the term `animal(gnu, 50)`, use:

      { term_t a1 = PL_new_term_ref();
        term_t a2 = PL_new_term_ref();
        term_t t  = PL_new_term_ref();
        functor_t animal2;

        /* animal2 is a constant that may be bound to a global
           variable and re-used
        */
        animal2 = PL_new_functor(PL_new_atom("animal"), 2);

        PL_put_atom_chars(a1, "gnu");
        PL_put_integer(a2, 50);
        PL_cons_functor(t, animal2, a1, a2);
      }

  After this sequence, the term-references a1 and a2 may be used for other purposes.

void PL_cons_functor_v(term_t -h, functor_t f, term_t a0)
  Creates a compound term like PL_cons_functor(), but a0 is an array of term references as returned by PL_new_term_refs(). The length of this array should match the number of arguments required by the functor.
void PL_cons_list(term_t -l, term_t +h, term_t +t)
  Create a list (cons-) cell in l from the head and tail. The code below creates a list of atoms from a `char **`. The list is built tail-to-head. The `PL_unify_*()` functions can be used to build a list head-to-tail.

      void
      put_list(term_t l, int n, char **words)
      { term_t a = PL_new_term_ref();

        PL_put_nil(l);
        while( --n >= 0 )
        { PL_put_atom_chars(a, words[n]);
          PL_cons_list(l, a, l);
        }
      }

  Note that l can be redefined within a `PL_cons_list` call as shown here because operationally its old value is consumed before its new value is set.

### 9.6.5 Unifying data

The functions of this sections unify terms with other terms or translated C-data structures. Except for PL_unify(), the functions of this section are specific to SWI-Prolog. They have been introduced to make translation of old code easier, but also because they provide for a faster mechanism for returning data to Prolog that requires less term-references. Consider the case where we want a foreign function to return the host name of the machine Prolog is running on. Using the `PL_get_*()` and `PL_put_*()` functions, the code becomes:

    foreign_t
    pl_hostname(term_t name)
    { char buf[100];

      if ( gethostname(buf, sizeof(buf)) )
      { term_t tmp = PL_new_term_ref();

        PL_put_atom_chars(tmp, buf);
        return PL_unify(name, tmp);
      }

      PL_fail;
    }

Using PL_unify_atom_chars(), this becomes:

    foreign_t
    pl_hostname(term_t name)
    { char buf[100];

      if ( gethostname(buf, sizeof(buf)) )
        return PL_unify_atom_chars(name, buf);

      PL_fail;
    }

int PL_unify(term_t ?t1, term_t ?t2)
  Unify two Prolog terms and return non-zero on success.
int PL_unify_atom(term_t ?t, atom_t a)
  Unify t with the atom a and return non-zero on success.
int PL_unify_chars(term_t ?t, int flags, size_t len, const char *chars)
  New function to deal with unification of `char*` with various encodings to a Prolog representation. The flags argument is a bitwise or specifying the Prolog target type and the encoding of chars. Prolog types is one of `PL_ATOM`, `PL_STRING`, `PL_CODE_LIST` or `PL_CHAR_LIST`. Representations is one of `REP_ISO_LATIN_1`, `REP_UTF8` or `REP_MB`. See PL_get_chars() for a definition of the representation types. If len is `-1` chars must be 0-terminated and the length is computed from chars using strlen().

  If flags includes `PL_DIFF_LIST` and type is one of `PL_CODE_LIST` or `PL_CHAR_LIST`, the text is converted to a difference list. The tail of the difference list is t+1.

int PL_unify_atom_chars(term_t ?t, const char *chars)
  Unify t with an atom created from chars and return non-zero on success.
int PL_unify_list_chars(term_t ?t, const char *chars)
  Unify t with a list of ASCII characters constructed from chars.
void PL_unify_string_chars(term_t ?t, const char *chars)
  Unify t with a Prolog string object created from the zero-terminated string chars. The data will be copied. See also PL_unify_string_nchars().
void PL_unify_string_nchars(term_t ?t, size_t len, const char *chars)
  Unify t with a Prolog string object created from the string created from the len/chars pair. The data will be copied. This interface can deal with 0-bytes in the string. See also section 9.6.19.
int PL_unify_integer(term_t ?t, long n)
  Unify t with a Prolog integer from n.
int PL_unify_int64(term_t ?t, int64_t n)
  Unify t with a Prolog integer from n.
int PL_unify_float(term_t ?t, double f)
  Unify t with a Prolog float from f.
int PL_unify_pointer(term_t ?t, void *ptr)
  Unify t with a Prolog integer describing the pointer. See also PL_put_pointer() and PL_get_pointer().
int PL_unify_functor(term_t ?t, functor_t f)
  If t is a compound term with the given functor, just succeed. If it is unbound, create a term and bind the variable, else fails. Note that this function does not create a term if the argument is already instantiated.
int PL_unify_list(term_t ?l, term_t -h, term_t -t)
  Unify l with a list-cell (`./2`). If successful, write a reference to the head of the list to h and a reference to the tail of the list into t. This reference may be used for subsequent calls to this function. Suppose we want to return a list of atoms from a `char **`. We could use the example described by PL_put_list(), followed by a call to PL_unify(), or we can use the code below. If the predicate argument is unbound, the difference is minimal (the code based on PL_put_list() is probably slightly faster). If the argument is bound, the code below may fail before reaching the end of the word-list, but even if the unification succeeds, this code avoids a duplicate (garbage) list and a deep unification.

      foreign_t
      pl_get_environ(term_t env)
      { term_t l = PL_copy_term_ref(env);
        term_t a = PL_new_term_ref();
        extern char **environ;
        char **e;

        for(e = environ; *e; e++)
        { if ( !PL_unify_list(l, a, l) ||
               !PL_unify_atom_chars(a, *e) )
            PL_fail;
        }

        return PL_unify_nil(l);
      }

int PL_unify_nil(term_t ?l)
  Unify l with the atom `[]`.
int PL_unify_arg(int index, term_t ?t, term_t ?a)
  Unifies the index-th argument (1-based) of t with a.
int PL_unify_term(term_t ?t, ...)
  Unify t with a (normally) compound term. The remaining arguments is a sequence of a type identifier, followed by the required arguments. This predicate is an extension to the Quintus and SICStus foreign interface from which the SWI-Prolog foreign interface has been derived, but has proved to be a powerful and comfortable way to create compound terms from C. Due to the vararg packing/unpacking and the required type-switching this interface is slightly slower than using the primitives. Please note that some bad C-compilers have fairly low limits on the number of arguments that may be passed to a function.

  Special attention is required when passing numbers. C `promotes' any integral smaller than `int` to `int`. I.e. the types `char`, `short` and `int` are all passed as `int`. In addition, on most 32-bit platforms `int` and `long` are the same. Up-to version 4.0.5, only `PL_INTEGER` could be specified which was taken from the stack as `long`. Such code fails when passing small integral types on machines where `int` is smaller than `long`. It is advised to use `PL_SHORT`, `PL_INT` or `PL_LONG` as appropriate. Similar, C compilers promote `float` to `double` and therefore `PL_FLOAT` and `PL_DOUBLE` are synonyms.

  The type identifiers are:

  `PL_VARIABLE` none
    No op. Used in arguments of `PL_FUNCTOR`.
  `PL_BOOL` int
    Unify the argument with `true` or `false`.
  `PL_ATOM` atom_t
    Unify the argument with an atom, as in PL_unify_atom().
  `PL_CHARS` const char *
    Unify the argument with an atom, constructed from the C `char *`, as in PL_unify_atom_chars().
  `PL_NCHARS` size_t, const char *
    Unify the argument with an atom, constructed from length and `char*` as in PL_unify_atom_nchars().
  `PL_UTF8_CHARS` const char *
    Create an atom from a UTF-8 string.
  `PL_UTF8_STRING` const char *
    Create a packed string object from a UTF-8 string.
  `PL_MBCHARS` const char *
    Create an atom from a multi-byte string in the current locale.
  `PL_MBCODES` const char *
    Create a list of character codes from a multi-byte string in the current locale.
  `PL_MBSTRING` const char *
    Create a packed string object from a multi-byte string in the current locale.
  `PL_NWCHARS` size_t, const wchar_t *
    Create an atom from a length and a wide character pointer.
  `PL_NWCODES` size_t, const wchar_t *
    Create an list of character codes from a length and a wide character pointer.
  `PL_NWSTRING` size_t, const wchar_t *
    Create a packed string object from a length and a wide character pointer.
  `PL_SHORT` short
    Unify the argument with an integer, as in PL_unify_integer(). As `short` is promoted to `int`, `PL_SHORT` is a synonym for `PL_INT`.
  `PL_INTEGER` long
    Unify the argument with an integer, as in PL_unify_integer().
  `PL_INT` int
    Unify the argument with an integer, as in PL_unify_integer().
  `PL_LONG` long
    Unify the argument with an integer, as in PL_unify_integer().
  `PL_INT64` int64_t
    Unify the argument with a 64-bit integer, as in PL_unify_int64().
  `PL_INTPTR` intptr_t
    Unify the argument with an integer with the same width as a pointer. On most machines this is the same as `PL_LONG`. but on 64-bit MS-Windows pointers are 64-bit while longs are only 32-bits.
  `PL_DOUBLE` double
    Unify the argument with a float, as in PL_unify_float(). Note that, as the argument is passed using the C vararg conventions, a float must be casted to a double explicitly.
  `PL_FLOAT` double
    Unify the argument with a float, as in PL_unify_float().
  `PL_POINTER` void *
    Unify the argument with a pointer, as in PL_unify_pointer().
  `PL_STRING` const char *
    Unify the argument with a string object, as in PL_unify_string_chars().
  `PL_TERM` term_t
    Unify a subterm. Note this may the return value of a PL_new_term_ref() call to get access to a variable.
  `PL_FUNCTOR` functor_t, ...
    Unify the argument with a compound term. This specification should be followed by exactly as many specifications as the number of arguments of the compound term.
  `PL_FUNCTOR_CHARS` const char *name, int arity, ...
    Create a functor from the given name and arity and then behave as `PL_FUNCTOR`.
  `PL_LIST` int length, ...
    Create a list of the indicated length. The following arguments contain the elements of the list.

  For example, to unify an argument with the term `language(dutch)`, the following skeleton may be used:

      static functor_t FUNCTOR_language1;

      static void
      init_constants()
      { FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"), 1);
      }

      foreign_t
      pl_get_lang(term_t r)
      { return PL_unify_term(r,
                             PL_FUNCTOR, FUNCTOR_language1,
                                 PL_CHARS, "dutch");
      }

      install_t
      install()
      { PL_register_foreign("get_lang", 1, pl_get_lang, 0);
        init_constants();
      }

int PL_chars_to_term(const char *chars, term_t -t)
  Parse the string chars and put the resulting Prolog term into t. chars may or may not be closed using a Prolog full-stop (i.e., a dot followed by a blank). Returns `FALSE` if a syntax error was encountered and `TRUE` after successful completion. In addition to returning `FALSE`, the exception-term is returned in t on a syntax error. See also term_to_atom/2.

  The following example build a goal-term from a string and calls it.

      int
      call_chars(const char *goal)
      { fid_t fid = PL_open_foreign_frame();
        term_t g = PL_new_term_ref();
        BOOL rval;

        if ( PL_chars_to_term(goal, g) )
          rval = PL_call(goal, NULL);
        else
          rval = FALSE;

        PL_discard_foreign_frame(fid);
        return rval;
      }

        ...
        call_chars("consult(load)");
        ...

char * PL_quote(int chr, const char *string)
  Return a quoted version of string. If chr is `'\''`, the result is a quoted atom. If chr is `'"'`, the result is a string. The result string is stored in the same ring of buffers as described with the `BUF_RING` argument of PL_get_chars();

  In the current implementation, the string is surrounded by chr and any occurrence of chr is doubled. In the future the behaviour will depend on the character_escapes Prolog flag.

### 9.6.6 BLOBS: Using atoms to store arbitrary binary data

SWI-Prolog atoms as well as strings can represent arbitrary binary data of arbitrary length. This facility is attractive for storing foreign data such as images in an atom. An atom is a unique handle to this data and the atom garbage collector is able to destroy atoms that are no longer referenced by the Prolog engine. This property of atoms makes them attractive as a handle to foreign resources, such as Java atoms, Microsoft's COM objects, etc., providing safe combined garbage collection.

To exploit these features safely and in an organised manner the SWI-Prolog foreign interface allows for creating `atoms' with additional type information. The type is represented by a structure holding C function pointers that tell Prolog how to handle releasing the atom, writing it, sorting it, etc. Two atoms created with different types can represent the same sequence of bytes. Atoms are first ordered on the rank number of the type and then on the result of the compare() function. Rank numbers are assigned when the type is registered.

#### 9.6.6.1 Defining a BLOB type

The type `PL_blob_t` represents a structure with the layout displayed above. The structure contains additional fields at the ... for internal bookkeeping as well as future extension.

    typedef struct PL_blob_t
    { unsigned long         magic;          /* PL_BLOB_MAGIC */
      unsigned long         flags;          /* Bitwise or of PL_BLOB_* */
      char *                name;           /* name of the type */
      int                   (*release)(atom_t a);
      int                   (*compare)(atom_t a, atom_t b);
      int                   (*write)(IOSTREAM *s, atom_t a, int flags);
      int                   (*acquire)(atom_t a);
      ...
    } PL_blob_t;

For each type exactly one such structure should be allocated. Its first field must be initialised to `PL_BLOB_MAGIC`. The flags is a bitwise or of the following constants:

PL_BLOB_TEXT
  If specified the blob is assumed to contain text and is considered a normal Prolog atom.
PL_BLOB_UNIQUE
  If specified the system ensures that the blob-handle is a unique reference for a blob with the given type, length and content. If this flag is not specified each lookup creates a new blob.
PL_BLOB_NOCOPY
  By default the content of the blob is copied. Using this flag the blob references the external data directly. The user must ensure the provided pointer is valid as long as the atom lives. If `PL_BLOB_UNIQUE` is also specified uniqueness is determined by comparing the pointer rather than the data pointed at.

The name field represents the type name as available to Prolog. See also current_blob/2. The other field are function pointers that must be initialised to proper functions or `NULL` to get the default behaviour of built-in atoms. Below are the defined member functions:

void acquire(atom_t a)
  Called if a new blob of this type is created through PL_put_blob() or PL_unify_blob(). This callback may be used together with the release hook to deal with reference counted external objects.
int release(atom_t a)
  The blob (atom) a is about to be released. This function can retrieve the data of the blob using PL_blob_data(). If it returns `FALSE` the atom garbage collector will not reclaim the atom.
int compare(atom_t a, atom_t b)
  Compare the blobs a and b, both of which are of the type associated to this blob-type. Return values are, as memcmp(), < 0 if a is less then b, = 0 if both are equal and > 0 otherwise.
int write(IOSTREAM *s, atom_t a, int flags)
  Write the content of the blob a to the stream s and respecting the flags. The flags are a bitwise or of zero or more of the `PL_WRT_*` flags defined in `SWI-Prolog.h`. This prototype is available if the undocumented `SWI-Stream.h` is included before `SWI-Prolog.h`.

  If this function is not provided, write/1 emits the content of the blob for blobs of type `PL_BLOB_TEXT` or a string of the format `<#`hex data`>` for binary blobs.

If a blob type is registered from a loadable object (shared object or DLL) the blob-type must be deregistered before the object may be released.

int PL_unregister_blob_type(PL_blob_t *type)
  Unlink the blob type from the registered type and transform the type of possible living blobs to `unregistered`, avoiding further reference to the type structure, functions referred by it as well as the data. This function returns `TRUE` if no blobs of this type existed and `FALSE` otherwise. PL_unregister_blob_type() is intended for the uninstall() hook of foreign modules, avoiding further references to the module.

#### 9.6.6.2 Accessing blobs

The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom functions operate on blobs and visa versa. For clarity and possible future compatibility issues however it is not advised to rely on this.

int PL_is_blob(term_t t, PL_blob_t **type)
  Succeeds if t refers to a blob, in which case type is filled with the type of the blob.
int PL_unify_blob(term_t t, void *blob, size_t len, PL_blob_t *type)
  Unify t to a new blob constructed from the given data and associated to the given type. See also PL_unify_atom_nchars().
int PL_put_blob(term_t t, void *blob, size_t len, PL_blob_t *type)
  Store the described blob in t. The return value indicates whether a new blob was allocated (`FALSE`) or the blob is a reference to an existing blob (`TRUE`). Reporting new/existing can be used to deal with external objects having their own reference counts. If the return is `TRUE` this reference count must be incremented and it must be decremented on blob destruction callback. See also PL_put_atom_nchars().
int PL_get_blob(term_t t, void **blob, size_t *len, PL_blob_t **type)
  If t holds a blob or atom get the data and type and return `TRUE`. Otherwise return `FALSE`. Each result pointer may be `NULL`, in which case the requested information is ignored.
void * PL_blob_data(atom_t a, size_t *len, PL_blob_t **type)
  Get the data and type associated to a blob. This function is mainly used from the callback functions described in section 9.6.6.1.

### 9.6.7 Exchanging GMP numbers

If SWI-Prolog is linked with the GNU Multiple Precision Arithmetic Library (GMP, used by default), the foreign interface provides functions for exchanging numeric values to GMP types. To access these functions the header `<gmp.h>` must be included before `<SWI-Prolog.h>`. Foreign code using GMP linked to SWI-Prolog asks for some considerations.

- SWI-Prolog normally rebinds the GMP allocation functions using mp_set_memory_functions(). This means SWI-Prolog must be initialised before the foreign code touches any GMP function. You can call `PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, TRUE)` to force Prolog's GMP initialization without doing the rest of the Prolog initialization. If you do not want Prolog rebinding the GMP allocation, call `PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, FALSE)` before initializing Prolog.

- On Windows, each DLL has its own memory pool. To make exchange of GMP numbers between Prolog and foreign code possible you must either let Prolog rebind the allocation functions (default) or you must recompile SWI-Prolog to link to a DLL version of the GMP library.

Here is an example exploiting the function mpz_nextprime():

    #include <gmp.h>
    #include <SWI-Prolog.h>

    static foreign_t
    next_prime(term_t n, term_t prime)
    { mpz_t mpz;
      int rc;

      mpz_init(mpz);
      if ( PL_get_mpz(n, mpz) )
      { mpz_nextprime(mpz, mpz);

        rc = PL_unify_mpz(prime, mpz);
      } else
        rc = FALSE;

      mpz_clear(mpz);
      return rc;
    }

    install_t
    install()
    { PL_register_foreign("next_prime", 2, next_prime, 0);
    }

int PL_get_mpz(term_t t, mpz_t mpz)
  If t represents an integer mpz is filled with the value and the function returns `TRUE`. Otherwise mpz is untouched and the function returns `FALSE`. Note that mpz must have been initialised before calling this function and must be cleared using mpz_clear() to reclaim any storage associated with it.
int PL_get_mpq(term_t t, mpq_t mpq)
  If t is an integer or rational number (term rdiv/2 ) mpq is filled with the normalise rational number and the function returns `TRUE`. Otherwise mpq is untouched and the function returns `FALSE`. Note that mpq must have been initialised before calling this function and must be cleared using mpq_clear() to reclaim any storage associated with it.
int PL_unify_mpz(term_t t, mpz_t mpz)
  Unify t with the integer value represented by mpz and return TRUE on success. The mpz argument is not changed.
int PL_unify_mpq(term_t t, mpq_t mpq)
  Unify t with a rational number represented by mpq and return TRUE on success. Note that t is unified with an integer if the denominator is 1. The mpq argument is not changed.

### 9.6.8 Calling Prolog from C

The Prolog engine can be called from C. There are two interfaces for this. For the first, a term is created that could be used as an argument to call/1 and next PL_call() is used to call Prolog. This system is simple, but does not allow to inspect the different answers to a non-deterministic goal and is relatively slow as the runtime system needs to find the predicate. The other interface is based on PL_open_query(), PL_next_solution() and PL_cut_query() or PL_close_query(). This mechanism is more powerful, but also more complicated to use.

#### 9.6.8.1 Predicate references

This section discusses the functions used to communicate about predicates. Though a Prolog predicate may defined or not, redefined, etc., a Prolog predicate has a handle that is not destroyed, nor moved. This handle is known by the type `predicate_t`.

predicate_t PL_pred(functor_t f, module_t m)
  Return a handle to a predicate for the specified name/arity in the given module. This function always succeeds, creating a handle for an undefined predicate if no handle was available. If the module argument m is `NULL`, the current context module is used.
predicate_t PL_predicate(const char *name, int arity, const char* module)
  Same a PL_pred(), but provides a more convenient interface to the C-programmer.
void PL_predicate_info(predicate_t p, atom_t *n, int *a, module_t *m)
  Return information on the predicate p. The name is stored over n, the arity over a, while m receives the definition module. Note that the latter need not be the same as specified with PL_predicate(). If the predicate is imported into the module given to PL_predicate(), this function will return the module where the predicate is defined.

#### 9.6.8.2 Initiating a query from C

This section discusses the functions for creating and manipulating queries from C. Note that a foreign context can have at most one active query. This implies it is allowed to make strictly nested calls between C and Prolog (Prolog calls C, calls Prolog, calls C, etc., but it is not allowed to open multiple queries and start generating solutions for each of them by calling PL_next_solution(). Be sure to call PL_cut_query() or PL_close_query() on any query you opened before opening the next or returning control back to Prolog.

qid_t PL_open_query(module_t ctx, int flags, predicate_t p, term_t +t0)

  Opens a query and returns an identifier for it. This function always succeeds, regardless whether the predicate is defined or not. ctx is the context module of the goal. When `NULL`, the context module of the calling context will be used, or `user` if there is no calling context (as may happen in embedded systems). Note that the context module only matters for module_transparent predicates. See context_module/1 and module_transparent/1. The p argument specifies the predicate, and should be the result of a call to PL_pred() or PL_predicate(). Note that it is allowed to store this handle as global data and reuse it for future queries. The term-reference t0 is the first of a vector of term-references as returned by PL_new_term_refs(n).

  The flags arguments provides some additional options concerning debugging and exception handling. It is a bitwise or of the following values:

  `PL_Q_NORMAL`
    Normal operation. The debugger inherits its settings from the environment. If an exception occurs that is not handled in Prolog, a message is printed and the tracer is started to debug the error.79Do not pass the integer 0 for normal operation, as this is interpreted as `PL_Q_NODEBUG` for backward compatibility reasons.
  `PL_Q_NODEBUG`
    Switch off the debugger while executing the goal. This option is used by many calls to hook-predicates to avoid tracing the hooks. An example is print/1 calling portray/1 from foreign code.
  `PL_Q_CATCH_EXCEPTION`
    If an exception is raised while executing the goal, do not report it, but make it available for PL_exception().
  `PL_Q_PASS_EXCEPTION`
    As `PL_Q_CATCH_EXCEPTION`, but do not invalidate the exception-term while calling PL_close_query(). This option is experimental.

  The example below opens a query to the predicate is_a/2 to find the ancestor of for some name.

      char *
      ancestor(const char *me)
      { term_t a0 = PL_new_term_refs(2);
        static predicate_t p;

        if ( !p )
          p = PL_predicate("is_a", 2, "database");

        PL_put_atom_chars(a0, me);
        PL_open_query(NULL, PL_Q_NORMAL, p, a0);
        ...
      }

int PL_next_solution(qid_t qid)
  Generate the first (next) solution for the given query. The return value is `TRUE` if a solution was found, or `FALSE` to indicate the query could not be proven. This function may be called repeatedly until it fails to generate all solutions to the query.
void PL_cut_query(qid)
  Discards the query, but does not delete any of the data created by the query. It just invalidate qid, allowing for a new call to PL_open_query() in this context.
void PL_close_query(qid)
  As PL_cut_query(), but all data and bindings created by the query are destroyed.
int PL_call_predicate(module_t m, int flags, predicate_t pred, term_t +t0)
  Shorthand for PL_open_query(), PL_next_solution(), PL_cut_query(), generating a single solution. The arguments are the same as for PL_open_query(), the return value is the same as PL_next_solution().
int PL_call(term_t, module_t)
  Call term just like the Prolog predicate once/1. Term is called in the specified module, or in the context module if module_t = NULL. Returns `TRUE` if the call succeeds, `FALSE` otherwise. Figure 10 shows an example to obtain the number of defined atoms. All checks are omitted to improve readability.

### 9.6.9 Discarding Data

The Prolog data created and term-references needed to setup the call and/or analyse the result can in most cases be discarded right after the call. PL_close_query() allows for destructing the data, while leaving the term-references. The calls below may be used to destroy term-references and data. See figure 10 for an example.

fid_t PL_open_foreign_frame()
  Created a foreign frame, holding a mark that allows the system to undo bindings and destroy data created after it as well as providing the environment for creating term-references. This function is called by the kernel before calling a foreign predicate.
void PL_close_foreign_frame(fid_t id)
  Discard all term-references created after the frame was opened. All other Prolog data is retained. This function is called by the kernel whenever a foreign function returns control back to Prolog.
void PL_discard_foreign_frame(fid_t id)
  Same as PL_close_foreign_frame(), but also undo all bindings made since the open and destroy all Prolog data.
void PL_rewind_foreign_frame(fid_t id)
  Undo all bindings and discard all term-references created since the frame was created, but does not pop the frame. I.e. the same frame can be rewinded multiple times, and must eventually be closed or discarded.

It is obligatory to call either of the two closing functions to discard a foreign frame. Foreign frames may be nested.

    int
    count_atoms()
    { fid_t fid = PL_open_foreign_frame();
      term_t goal  = PL_new_term_ref();
      term_t a1    = PL_new_term_ref();
      term_t a2    = PL_new_term_ref();
      functor_t s2 = PL_new_functor(PL_new_atom("statistics"), 2);
      int atoms;

      PL_put_atom_chars(a1, "atoms");
      PL_cons_functor(goal, s2, a1, a2);
      PL_call(goal, NULL);         /* call it in current module */

      PL_get_integer(a2, &atoms);
      PL_discard_foreign_frame(fid);

      return atoms;
    }

Figure 10 : Calling Prolog

### 9.6.10 Foreign Code and Modules

Modules are identified via a unique handle. The following functions are available to query and manipulate modules.

module_t PL_context()
  Return the module identifier of the context module of the currently active foreign predicate.
int PL_strip_module(term_t +raw, module_t *m, term_t -plain)
  Utility function. If raw is a term, possibly holding the module construct <module>`:`<rest> this function will make plain a reference to <rest> and fill module * with <module>. For further nested module constructs the inner most module is returned via module *. If raw is not a module construct arg will simply be put in plain. If module * is `NULL` it will be set to the context module. Otherwise it will be left untouched. The following example shows how to obtain the plain term and module if the default module is the user module:

      { module m = PL_new_module(PL_new_atom("user"));
        term_t plain = PL_new_term_ref();

        PL_strip_module(term, &m, plain);
        ...

atom_t PL_module_name(module_t)
  Return the name of module as an atom.
module_t PL_new_module(atom_t name)
  Find an existing or create a new module with name specified by the atom name.

### 9.6.11 Prolog exceptions in foreign code

This section discusses PL_exception(), PL_throw() and PL_raise_exception(), the interface functions to detect and generate Prolog exceptions from C-code. PL_throw() and PL_raise_exception() from the C-interface to raise an exception from foreign code. PL_throw() exploits the C-function longjmp() to return immediately to the innermost PL_next_solution(). PL_raise_exception() registers the exception term and returns `FALSE`. If a foreign predicate returns FALSE, while and exception-term is registered a Prolog exception will be raised by the virtual machine.

Calling these functions outside the context of a function implementing a foreign predicate results in undefined behaviour.

PL_exception() may be used after a call to PL_next_solution() fails, and returns a term reference to an exception term if an exception was raised, and 0 otherwise.

If a C-function, implementing a predicate calls Prolog and detects an exception using PL_exception(), it can handle this exception, or return with the exception. Some caution is required though. It is not allowed to call PL_close_query() or PL_discard_foreign_frame() afterwards, as this will invalidate the exception term. Below is the code that calls a Prolog defined arithmetic function (see arithmetic_function/1).

If PL_next_solution() succeeds, the result is analysed and translated to a number, after which the query is closed and all Prolog data created after PL_open_foreign_frame() is destroyed. On the other hand, if PL_next_solution() fails and if an exception was raised, just pass it. Otherwise generate an exception (PL_error() is an internal call for building the standard error terms and calling PL_raise_exception()). After this, the Prolog environment should be discarded using PL_cut_query() and PL_close_foreign_frame() to avoid invalidating the exception term.

    static int
    prologFunction(ArithFunction f, term_t av, Number r)
    { int arity = f->proc->definition->functor->arity;
      fid_t fid = PL_open_foreign_frame();
      qid_t qid;
      int rval;

      qid = PL_open_query(NULL, PL_Q_NORMAL, f->proc, av);

      if ( PL_next_solution(qid) )
      { rval = valueExpression(av+arity-1, r);
        PL_close_query(qid);
        PL_discard_foreign_frame(fid);
      } else
      { term_t except;

        if ( (except = PL_exception(qid)) )
        { rval = PL_throw(except);          /* pass exception */
        } else
        { char *name = stringAtom(f->proc->definition->functor->name);

                                            /* generate exception */
          rval = PL_error(name, arity-1, NULL, ERR_FAILED, f->proc);
        }

        PL_cut_query(qid);                  /* donot destroy data */
        PL_close_foreign_frame(fid);        /* same */
      }

      return rval;
    }

int PL_raise_exception(term_t exception)
  Generate an exception (as throw/1) and return `FALSE`. Below is an example returning an exception from foreign predicate:

      foreign_t
      pl_hello(term_t to)
      { char *s;

        if ( PL_get_atom_chars(to, &s) )
        { Sprintf("Hello \"%s\"\n", s);

          PL_succeed;
        } else
        { term_t except = PL_new_term_ref();

          PL_unify_term(except,
                        PL_FUNCTOR_CHARS, "type_error", 2,
                          PL_CHARS, "atom",
                          PL_TERM, to);

          return PL_raise_exception(except);
        }
      }

int PL_throw(term_t exception)
  Similar to PL_raise_exception(), but returns using the C longjmp() function to the innermost PL_next_solution().
term_t PL_exception(qid_t qid)
  If PL_next_solution() fails, this can be due to normal failure of the Prolog call, or because an exception was raised using throw/1. This function returns a handle to the exception term if an exception was raised, or 0 if the Prolog goal simply failed.80This interface differs in two ways from Quintus. The calling predicates simply signal failure if an exception was raised, and a term referenced is returned, rather passed and filled with the error term. Exceptions can only be handled using the PL_next_solution() interface, as a handle to the query is required.

### 9.6.12 Catching Signals (Software Interrupts)

SWI-Prolog offers both a C and Prolog interface to deal with software interrupts (signals). The Prolog mapping is defined in section 4.10. This subsection deals with handling signals from C.

If a signal is not used by Prolog and the handler does not call Prolog in any way, the native signal interface routines may be used.

Some versions of SWI-Prolog, notably running on popular Unix platforms, handle `SIG_SEGV` for guarding the Prolog stacks. If the application wishes to handle this signal too, it should use PL_signal() to install its handler after initialising Prolog. SWI-Prolog will pass `SIG_SEGV` to the user code if it detected the signal is not related to a Prolog stack overflow.

Any handler that wishes to call one of the Prolog interface functions should call PL_signal() for its installation.

void (*)() PL_signal(sig, func)
  This function is equivalent to the BSD-Unix signal() function, regardless of the platform used. The signal handler is blocked while the signal routine is active, and automatically reactivated after the handler returns.

  After a signal handler is registered using this function, the native signal interface redirects the signal to a generic signal handler inside SWI-Prolog. This generic handler validates the environment, creates a suitable environment for calling the interface functions described in this chapter and finally calls the registered user-handler.

  By default, signals are handled asynchronously (i.e. at the time they arrive). It is inherently dangerous to call extensive code fragments, and especially exception related code from asynchronous handlers. The interface allows for synchronous handling of signals. In this case the native OS handler just schedules the signal using PL_raise(), which is checked by PL_handle_signals() at the call- and redo-port. This behaviour is realised by or-ing sig with the constant `PL_SIGSYNC`.81A better default would be to use synchronous handling, but this interface preserves backward compatibility.

  Signal handling routines may raise exceptions using PL_raise_exception(). The use of PL_throw() is not safe. If a synchronous handler raises an exception, the exception is delayed to the next call to PL_handle_signals();

int PL_raise(int sig)
  Register sig for synchronous handling by Prolog. Synchronous signals are handled at the call-port or if foreign code calls PL_handle_signals(). See also thread_signal/2.
int PL_handle_signals(void)
  Handle any signals pending from PL_raise(). PL_handle_signals() is called at each pass through the call- and redo-port at a safe point. Exceptions raised by the handler using PL_raise_exception() are properly passed to the environment.

  The user may call this function inside long-running foreign functions to handle scheduled interrupts. This routine returns the number of signals handled. If a handler raises an exception, the return value is -1 and the calling routine should return with `FALSE` as soon as possible.

int PL_get_signum_ex(term_t t, int *sig)
  Extract a signal specification from a Prolog term and store as integer signal number in sig. The specification is an integer, lowercase signal name without `SIG` or the full signal name. These refer to the same: `9`, `kill` and `SIGKILL`. Leaves a typed, domain or instantiation error if the conversion fails.

### 9.6.13 Miscellaneous

#### 9.6.13.1 Term Comparison

int PL_compare(term_t t1, term_t t2)
  Compares two terms using the standard order of terms and returns -1, 0 or 1. See also compare/3.
int PL_same_compound(term_t t1, term_t t2)
  Yields `TRUE` if t1 and t2 refer to physically the same compound term and `FALSE` otherwise.

#### 9.6.13.2 Recorded database

In some applications it is useful to store and retrieve Prolog terms from C-code. For example, the XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects.

Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog. The functions PL_recorded() and PL_erase() are the only functions that can operate on the stored term.

Two groups of functions are provided. The first group (PL_record() and friends) store Prolog terms on the Prolog heap for retrieval during the same session. These functions are also used by recorda/3 and friends. The recorded database may be used to communicate Prolog terms between threads.

record_t PL_record(term_t +t)
  Record the term t into the Prolog database as recorda/3 and return an opaque handle to the term. The returned handle remains valid until PL_erase() is called on it. PL_recorded() is used to copy recorded terms back to the Prolog stack.
void PL_recorded(record_t record, term_t -t)
  Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also PL_record() and PL_erase().
void PL_erase(record_t record)
  Remove the recorded term from the Prolog database, reclaiming all associated memory resources.

The second group (headed by PL_record_external()) provides the same functionality, but the returned data has properties that enable storing the data on an external device. It has been designed to make it possible to store Prolog terms fast an compact in an external database. Here are the main features:

- Independent of session
  Records can be communicated to another Prolog session and made visible using PL_recorded_external().
- Binary
  The representation is binary for maximum performance. The returned data may contain 0-bytes.
- Byte-order independent
  The representation can be transferred between machines with different byte-order.
- No alignment restrictions
  There are no memory alignment restrictions and copies of the record can thus be moved freely. For example, it is possible to use this representation to exchange terms using shared memory between different Prolog processes.
- Compact
  It is assumed that a smaller memory footprint will eventually outperform slightly faster representations.
- Stable
  The format is designed for future enhancements without breaking compatibility with older records.

char * PL_record_external(term_t +t, size_t *len)
  Record the term t into the Prolog database as recorda/3 and return an opaque handle to the term. The returned handle remains valid until PL_erase_external() is called on it.

  It is allowed to copy the data and use PL_recorded_external() on the copy. The user is responsible for the memory management of the copy. After copying, the original may be discarded using PL_erase_external().

  PL_recorded_external() is used to copy such recorded terms back to the Prolog stack.

int PL_recorded_external(const char *record, term_t -t)
  Copy a recorded term back to the Prolog stack. The same record may be used to copy multiple instances at any time to the Prolog stack. See also PL_record_external() and PL_erase_external().
int PL_erase_external(char *record)
  Remove the recorded term from the Prolog database, reclaiming all associated memory resources.

#### 9.6.13.3 Getting file names

The function PL_get_file_name() provides access to Prolog filenames and its file-search mechanism described with absolute_file_name/3. Its existence is motivated to realise a uniform interface to deal with file-properties, search, naming conventions etc. from foreign code.

int PL_get_file_name(term_t spec, char **name, int flags)
  Translate a Prolog term into a file name. The name is stored in the static buffer ring described with PL_get_chars() option `BUF_RING`. Conversion from the internal UNICODE encoding is done using standard C library functions. flags is a bit-mask controlling the conversion process. Options are:
  `PL_FILE_ABSOLUTE`
    Return an absolute path to the requested file.
  `PL_FILE_OSPATH`
    Return a the name using the hosting OS conventions. On MS-Windows, ``\`` is used to separate directories rather than the canonical ``/``.
  `PL_FILE_SEARCH`
    Invoke absolute_file_name/3. This implies rules from file_search_path/2 are used.
  `PL_FILE_EXIST`
    Demand the path to refer to an existing entity.
  `PL_FILE_READ`
    Demand read-access on the result.
  `PL_FILE_WRITE`
    Demand write-access on the result.
  `PL_FILE_EXECUTE`
    Demand execute-access on the result.
  `PL_FILE_NOERRORS`
    Do not raise any exceptions.

### 9.6.14 Errors and warnings

PL_warning() prints a standard Prolog warning message to the standard error (`user_error`) stream. Please note that new code should consider using PL_raise_exception() to raise a Prolog exception. See also section 4.9.

int PL_warning(format, a1, ...)
  Print an error message starting with ``[WARNING:` ', followed by the output from format, followed by a ``]`' and a newline. Then start the tracer. format and the arguments are the same as for printf(2). Always returns `FALSE`.

### 9.6.15 Environment Control from Foreign Code

int PL_action(int, ...)
  Perform some action on the Prolog system. int describes the action, Remaining arguments depend on the requested action. The actions are listed in table 6.

  > `PL_ACTION_TRACE` | Start Prolog tracer (trace/0). Requires no arguments.
  > `PL_ACTION_DEBUG` | Switch on Prolog debug mode (debug/0). Requires no arguments.
  > `PL_ACTION_BACKTRACE` | Print backtrace on current output stream. The argument (an int) is the number of frames printed.
  > `PL_ACTION_HALT` | Halt Prolog execution. This action should be called rather than Unix exit() to give Prolog the opportunity to clean up. This call does not return. The argument (an int) is the exit code. See halt/1.
  > `PL_ACTION_ABORT` | Generate a Prolog abort (abort/0). This call does not return. Requires no arguments.
  > `PL_ACTION_BREAK` | Create a standard Prolog break environment (break/0). Returns after the user types the end-of-file character. Requires no arguments.
  > `PL_ACTION_GUIAPP` | Win32: Used to indicate the kernel that the application is a GUI application if the argument is not 0 and a console application if the argument is 0. If a fatal error occurs, the system uses a windows messagebox to report this on a GUI application and simply prints the error and exits otherwise.
  > `PL_ACTION_WRITE` | Write the argument, a `char *` to the current output stream.
  > `PL_ACTION_FLUSH` | Flush the current output stream. Requires no arguments.
  > `PL_ACTION_ATTACH_CONSOLE` | Attach a console to a thread if it does not have one. See attach_console/0.
  > `PL_GMP_SET_ALLOC_FUNCTIONS` | Takes and integer argument. If `TRUE`, the GMP allocation are immediately bound to the Prolog functions. If `FALSE`, SWI-Prolog will never rebind the GMP allocation functions. See mp_set_memory_functions() in the GMP documentation. The action returns `FALSE` if there is no GMP support or GMP is already initialised.

  Table 6 : PL_action() options

### 9.6.16 Querying Prolog

long PL_query(int)
  Obtain status information on the Prolog system. The actual argument type depends on the information required. int describes what information is wanted.82Returning pointers and integers as a long is bad style. The signature of this function should be changed. The options are given in table 7.

  > `PL_QUERY_ARGC` | Return an integer holding the number of arguments given to Prolog from Unix.
  > `PL_QUERY_ARGV` | Return a char ** holding the argument vector given to Prolog from Unix.
  > `PL_QUERY_SYMBOLFILE` | Return a char * holding the current symbol file of the running process.
  > `PL_MAX_INTEGER` | Return a long, representing the maximal integer value represented by a Prolog integer.
  > `PL_MIN_INTEGER` | Return a long, representing the minimal integer value.
  > `PL_QUERY_VERSION` | Return a long, representing the version as 10,000 × M + 100 × m + p, where M is the major, m the minor version number and p the patch-level. For example, `20717` means `2.7.17`.
  > `PL_QUERY_MAX_THREADS` | Return the maximum number of threads that can be created in this version. Return values of PL_thread_self() are between 0 and this number.
  > `PL_QUERY_ENCODING` | Return the default stream encoding of Prolog (of type `IOENC`).
  > `PL_QUERY_USER_CPU` | Get amount of user CPU time of the process in milliseconds.

  Table 7 : PL_query() options

### 9.6.17 Registering Foreign Predicates

int PL_register_foreign_in_module(const char *module, const char *name, int arity, foreign_t (*function)(), int flags)
  Register a C-function to implement a Prolog predicate. After this call returns successfully a predicate with name name (a char *) and arity arity (a C int) is created in module module. If module is `NULL`, the predicate is created in the module of the calling context or if no context is present in the module `user`.

  When called in Prolog, Prolog will call function. flags forms bitwise or'ed list of options for the installation. These are:

  `PL_FA_NOTRACE` | Predicate cannot be seen in the tracer
  `PL_FA_TRANSPARENT` | Predicate is module transparent
  `PL_FA_NONDETERMINISTIC` | Predicate is non-deterministic. See also PL_retry().
  `PL_FA_VARARGS` | Use alternative calling convention.

  Predicates may be registered either before or after PL_initialise(). When registered before initialisation the registration is recorded and executed after installing the system predicates and before loading the saved state.

  Default calling (i.e. without `PL_FA_VARARGS`) function is passed the same number of term_t arguments as the arity of the predicate and, if the predicate is non-deterministic, an extra argument of type `control_t` (see section 9.6.1.1). If `PL_FA_VARARGS` is provided, function is called with three arguments. The first argument is a `term_t` handle to the first argument. Further arguments can be reached by adding the offset (see also PL_new_term_refs()). The second argument is the arity, which defines the number of valid term-references in the argument vector. The last argument is used for non-deterministic calls. It is currently undocumented and should be defined of type `void*`. Here is an example:

      static foreign_t
      atom_checksum(term_t a0, int arity, void* context)
      { char *s;

        if ( PL_get_atom_chars(a0, &s) )
        { int sum;

          for(sum=0; *s; s++)
            sum += *s&0xff;

          return PL_unify_integer(a0+1, sum&0xff);
        }

        return FALSE;
      }

      install_t
      install()
      { PL_register_foreign("atom_checksum", 2, atom_checksum, PL_FA_VARARGS);
      }

int PL_register_foreign(const char *name, int arity, foreign_t (*function)(), int flags)
  Same as PL_register_foreign_in_module(), passing `NULL` for the module.
void PL_register_extensions_in_module(const char *module, PL_extension *e)
  Register a series of predicates from an array of definitions of the type `PL_extension` in the given module. If module is `NULL`, the predicate is created in the module of the calling context or if no context is present in the module `user`. The `PL_extension` type is defined as

      typedef struct PL_extension
      { char          *predicate_name;        /* Name of the predicate */
        short         arity;                  /* Arity of the predicate */
        pl_function_t function;               /* Implementing functions */
        short         flags;                  /* Or of PL_FA_... */
      } PL_extension;

  For details, see PL_register_foreign_in_module(). Here is an example of its usage:

      static PL_extension predicates[] = {
      { "foo",        1,      pl_foo, 0 },
      { "bar",        2,      pl_bar, PL_FA_NONDETERMINISTIC },
      { NULL,         0,      NULL,   0 }
      };

      main(int argc, char **argv)
      { PL_register_extensions_in_module("user", predicates);

        if ( !PL_initialise(argc, argv) )
          PL_halt(1);

        ...
      }

void PL_register_extensions( PL_extension *e)
  Same as PL_register_extensions_in_module() using `NULL` for the module argument.

### 9.6.18 Foreign Code Hooks

For various specific applications some hooks re provided.

PL_dispatch_hook_t PL_dispatch_hook(PL_dispatch_hook_t)
  If this hook is not NULL, this function is called when reading from the terminal. It is supposed to dispatch events when SWI-Prolog is connected to a window environment. It can return two values: `PL_DISPATCH_INPUT` indicates Prolog input is available on file descriptor 0 or `PL_DISPATCH_TIMEOUT` to indicate a timeout. The old hook is returned. The type `PL_dispatch_hook_t` is defined as:

      typedef int  (*PL_dispatch_hook_t)(void);

void PL_abort_hook(PL_abort_hook_t)
  Install a hook when abort/0 is executed. SWI-Prolog abort/0 is implemented using C setjmp()/longjmp() construct. The hooks are executed in the reverse order of their registration after the longjmp() took place and before the Prolog top-level is reinvoked. The type `PL_abort_hook_t` is defined as:

      typedef void (*PL_abort_hook_t)(void);

int PL_abort_unhook(PL_abort_hook_t)
  Remove a hook installed with PL_abort_hook(). Returns `FALSE` if no such hook is found, `TRUE` otherwise.
void PL_on_halt(void (*f)(int, void *), void *closure)
  Register the function f to be called if SWI-Prolog is halted. The function is called with two arguments: the exit code of the process (0 if this cannot be determined on your operating system) and the closure argument passed to the PL_on_halt() call. See also at_halt/1.
PL_agc_hook_t PL_agc_hook(PL_agc_hook_t new)
  Register a hook with the atom-garbage collector (see garbage_collect_atoms/0 that is called on any atom that is reclaimed. The old hook is returned. If no hook is currently defined, `NULL` is returned. The argument of the called hook is the atom that is to be garbage collected. The return value is an `int`. If the return value is zero, the atom is not reclaimed. The hook may invoke any Prolog predicate.

  The example below defines a foreign library for printing the garbage collected atoms for debugging purposes.

      #include <SWI-Stream.h>
      #include <SWI-Prolog.h>

      static int
      atom_hook(atom_t a)
      { Sdprintf("AGC: deleting %s\n", PL_atom_chars(a));

        return TRUE;
      }

      static PL_agc_hook_t old;

      install_t
      install()
      { old = PL_agc_hook(atom_hook);
      }

      install_t
      uninstall()
      { PL_agc_hook(old);
      }

### 9.6.19 Storing foreign data

This section provides some hints for handling foreign data in Prolog. With foreign data, we refer to data that is used by foreign language predicates and needs to be passed around in Prolog. Excluding combinations, there are three principal options for storing such data

- Natural Prolog data
  E.i. using the representation one would choose if there was no foreign interface required.
- Opaque packed Prolog data
  Data can also be represented in a foreign structure and stored on the Prolog stacks using PL_put_string_nchars() and retrieved using PL_get_string_chars(). It is generally good practice to wrap the string in a compound term with arity 1, so Prolog can identify the type. portray/1 rules may be used to streamline printing such terms during development.
- Natural foreign data, passing a pointer
  An alternative is to pass a pointer to the foreign data. Again, this functor may be wrapped in a compound term.

The choice may be guided using the following distinctions

- Is the data opaque to Prolog
  With `opaque' data, we refer to data handled in foreign functions, passed around in Prolog, but of which Prolog never examines the contents of the data itself. If the data is opaque to Prolog, the chosen representation does not depend on simple analysis by Prolog, and the selection will be driven solely by simplicity of the interface and performance (both in time and space).
- How big is the data
  Is efficient encoding required? For examine, a boolean array may be expressed as a compound term, holding integers each of which contains a number of bits, or as a list of `true` and `false`.
- What is the nature of the data
  For examples in C, constants are often expressed using `enum' or #define'd integer values. If prolog needs to handle this data, atoms are a more logical choice. Whether or not this mapping is used depends on whether Prolog needs to interpret the data, how important debugging is and how important performance is.
- What is the lifetime of the data
  We can distinguish three cases.
  1. The lifetime is dictated by the accessibility of the data on the Prolog stacks. Their is no way by which the foreign code when the data becomes `garbage', and the data thus needs to be represented on the Prolog stacks using Prolog data-types. (2),
  2. The data lives on the `heap' and is explicitly allocated and deallocated. In this case, representing the data using native foreign representation and passing a pointer to it is a sensible choice.
  3. The data lives as during the lifetime of a foreign predicate. If the predicate is deterministic, foreign automatic variables are suitable. if the predicate is non-deterministic, the data may be allocated using malloc() and a pointer may be passed. See section 9.6.1.1.

#### 9.6.19.1 Examples for storing foreign data

In this section, we will outline some examples, covering typical cases. In the first example, we will deal with extending Prolog's data representation with integer-sets, represented as bit-vectors. Finally, we discuss the outline of the DDE interface.

Integer sets with not-too-far-apart upper- and lower-bounds can be represented using bit-vectors. Common set operations, such as union, intersection, etc. are reduced to simple and'ing and or'ing the bit-vectors. This can be done using Prolog's unbounded integers.

For really demanding applications, foreign representation will perform better, especially time-wise. Bit-vectors are naturally expressed using string objects. If the string is wrapped in bitvector/1 , lower-bound of the vector is 0, and the upper-bound is not defined, an implementation for getting and putting the sets as well as the union predicate for it is below.

    #include <SWI-Prolog.h>

    #define max(a, b) ((a) > (b) ? (a) : (b))
    #define min(a, b) ((a) < (b) ? (a) : (b))

    static functor_t FUNCTOR_bitvector1;

    static int
    get_bitvector(term_t in, int *len, unsigned char **data)
    { if ( PL_is_functor(in, FUNCTOR_bitvector1) )
      { term_t a = PL_new_term_ref();

        PL_get_arg(1, in, a);
        return PL_get_string(a, (char **)data, len);
      }

      PL_fail;
    }

    static int
    unify_bitvector(term_t out, int len, const unsigned char *data)
    { if ( PL_unify_functor(out, FUNCTOR_bitvector1) )
      { term_t a = PL_new_term_ref();

        PL_get_arg(1, out, a);

        return PL_unify_string_nchars(a, len, (const char *)data);
      }

      PL_fail;
    }

    static foreign_t
    pl_bitvector_union(term_t t1, term_t t2, term_t u)
    { unsigned char *s1, *s2;
      int l1, l2;

      if ( get_bitvector(t1, &l1, &s1) &&
           get_bitvector(t2, &l2, &s2) )
      { int l = max(l1, l2);
        unsigned char *s3 = alloca(l);

        if ( s3 )
        { int n;
          int ml = min(l1, l2);

          for(n=0; n<ml; n++)
            s3[n] = s1[n] | s2[n];
          for( ; n < l1; n++)
            s3[n] = s1[n];
          for( ; n < l2; n++)
            s3[n] = s2[n];

          return unify_bitvector(u, l, s3);
        }

        return PL_warning("Not enough memory");
      }

      PL_fail;
    }

    install_t
    install()
    { PL_register_foreign("bitvector_union", 3, pl_bitvector_union, 0);

      FUNCTOR_bitvector1 = PL_new_functor(PL_new_atom("bitvector"), 1);
    }

The DDE interface (see section 4.42) represents another common usage of the foreign interface: providing communication to new operating system features. The DDE interface requires knowledge about active DDE server and client channels. These channels contains various foreign data-types. Such an interface is normally achieved using an open/close protocol that creates and destroys a handle. The handle is a reference to a foreign data-structure containing the relevant information.

There are a couple of possibilities for representing the handle. The choice depends on responsibilities and debugging facilities. The simplest approach is to using PL_unify_pointer() and PL_get_pointer(). This approach is fast and easy, but has the drawbacks of (untyped) pointers: there is no reliable way to detect the validity of the pointer, not to verify it is pointing to a structure of the desired type. The pointer may be wrapped into a compound term with arity 1 (i.e., `dde_channel(<Pointer>)`), making the type-problem less serious.

Alternatively (used in the DDE interface), the interface code can maintain a (preferably variable length) array of pointers and return the index in this array. This provides better protection. Especially for debugging purposes, wrapping the handle in a compound is a good suggestion.

### 9.6.20 Embedding SWI-Prolog in other applications

With embedded Prolog we refer to the situation where the `main' program is not the Prolog application. Prolog is sometimes embedded in C, C++, Java or other languages to provide logic based services in a larger application. Embedding loads the Prolog engine as a library to the external language. Prolog itself only provides for embedding in the C-language (compatible to C++). Embedding in Java is achieved using JPL using a C-glue between the Java and Prolog C-interfaces.

The most simple embedded program is below. The interface function PL_initialise() must be called before any of the other SWI-Prolog foreign language functions described in this chapter, except for PL_initialise_hook(), PL_new_atom(), PL_new_functor() and PL_register_foreign(). PL_initialise() interprets all the command-line arguments, except for the -t toplevel flag that is interpreted by PL_toplevel().

    int
    main(int argc, char **argv)
    {
    #ifdef READLINE /* Remove if you don't want readline */
      PL_initialise_hook(install_readline);
    #endif

      if ( !PL_initialise(argc, argv) )
        PL_halt(1);

      PL_halt(PL_toplevel() ? 0 : 1);
    }

int PL_initialise(int argc, char **argv)
  Initialises the SWI-Prolog heap and stacks, restores the Prolog state, loads the system and personal initialisation files, runs the at_initialization/1 hooks and finally runs the -g goal hook.

  Special consideration is required for `argv[0]`. On Unix, this argument passes the part of the command-line that is used to locate the executable. Prolog uses this to find the file holding the running executable. The Windows version uses this to find a module of the running executable. If the specified module cannot be found, it tries the module `libpl.dll`, containing the Prolog runtime kernel. In all these cases, the resulting file is used for two purposes

  - See whether a Prolog saved-state is appended to the file. If this is the case, this state will be loaded instead of the default `boot.prc` file from the SWI-Prolog home directory. See also qsave_program/[1,2] and section 9.7.
  - Find the Prolog home directory. This process is described in detail in section 9.8.

  PL_initialise() returns 1 if all initialisation succeeded and 0 otherwise.bugVarious fatal errors may cause PL_initialise to call PL_halt(1), preventing it from returning at all.

  In most cases, argc and argv will be passed from the main program. It is allowed to create your own argument vector, provided `argv[0]` is constructed according to the rules above. For example:

      int
      main(int argc, char **argv)
      { char *av[10];
        int ac = 0;

        av[ac++] = argv[0];
        av[ac++] = "-x";
        av[ac++] = "mystate";
        av[ac]   = NULL;

        if ( !PL_initialise(ac, av) )
          PL_halt(1);
        ...
      }

  Please note that the passed argument vector may be referred from Prolog at any time and should therefore be valid as long as the Prolog engine is used.

  A good setup in Windows is to add SWI-Prolog's `bin` directory to your `PATH` and either pass a module holding a saved-state, or `"libpl.dll"` as `argv[0]`. If the Prolog state is attached to a DLL (see the -dll option of plld, pass the name of this DLL.

int PL_is_initialised(int *argc, char ***argv)
  Test whether the Prolog engine is already initialised. Returns `FALSE` if Prolog is not initialised and `TRUE` otherwise. If the engine is initialised and argc is not `NULL`, the argument count used with PL_initialise() is stored in argc. Same for the argument vector argv.
void PL_install_readline()
  Installs the GNU-readline line-editor. Embedded applications that do not use the Prolog top-level should normally delete this line, shrinking the Prolog kernel significantly. Note that the Windows version does not use GNU readline.
int PL_toplevel()
  Runs the goal of the -t toplevel switch (default prolog/0) and returns 1 if successful, 0 otherwise.
void PL_cleanup(int status)
  This function performs the reverse of PL_initialise(). It runs the PL_on_halt() and at_halt/1 handlers, closes all streams (except for the `standard I/O' streams which are flushed only), deallocates all memory and restores all signal handlers. The status argument is passed to the various termination hooks and indicates the exit-status.

  This function allows deleting and restarting the Prolog system in the same process. Use it with care, as PL_initialise() is a costly function. Unix users should consider using exec() (available as part of the clib package,).

void PL_cleanup_fork()
  Close file descriptors associated to Prolog streams except for 0,1 and 2. Stop intervaltimer that may be running on behalf of profile/1. The call is intended to be used in combination with fork():

          if ( (pid=fork()) == 0 )
          { PL_cleanup_fork();
            <some exec variation>
          }

  The call behaves the same on Windows, though there is probably no meaningful application.

int PL_halt(int status)
  Cleanup the Prolog environment using PL_cleanup() and calls exit() with the status argument. As PL_cleanup() can only be called from the main thread, this function returns `FALSE` when called from another thread as the main one.bugEventually it may become possible to call PL_halt() from any thread.

#### 9.6.20.1 Threading, Signals and embedded Prolog

This section applies to Unix-based environments that have signals or multi-threading. The Windows version is compiled for multi-threading and Windows lacks proper signals.

We can distinguish two classes of embedded executables. There are small C/C++-programs that act as an interfacing layer around Prolog. Most of these programs can be replaced using the normal Prolog executable extended with a dynamically loaded foreign extension and in most cases this is the preferred route. In other cases, Prolog is embedded in a complex application that---like Prolog---wants to control the process environment. A good example is Java. Embedding Prolog is generally the only way to get these environments together in one process image. Java applications however are by nature multi-threaded and appear to do signal-handling (software interrupts).

To make Prolog operate smoothly in such environments it must be told not to alter the process environment. This is partly done at build-time and partly execution time. At build-time we must specify the use of software stack-overflow rather then the default hardware checks. This is done using

    sh configure --disable-segv-handling

The resulting Prolog executable is about 10% slower than the normal executable, but behaves much more reliable in complicated embedded situations. In addition, as the process no longer handles segmentation violations, debugging foreign code linked to it is much easier.

At runtime, it is advised to pass the flag -nosignals, which inhibits all default signal handling. This has a few consequences though:

- It is no longer possible to break into the tracer using an interrupt signal (Control-C).
- `SIGPIPE` is normally set to be ignored. Prolog uses return-codes to diagnose broken pipes. Depending on the situation one should take appropriate action if Prolog streams are connected to pipes.
- Fatal errors normally cause Prolog to call PL_cleanup() and exit(). It is advised to call PL_cleanup() as part of the exit-procedure of your application.