xref: /dports/lang/swi-pl/swipl-8.2.3/man/foreign.doc

\chapter{Foreign Language Interface}		\label{sec:foreign}

\newlength{\tableft}
\settowidth{\tableft}{\const{PL_QUERY_ORGSYMBOLFILE}}

SWI-Prolog offers a powerful interface to C \cite{Kernighan:78}. The
main design objectives of the foreign language interface are flexibility
and performance. A foreign predicate is a C function that has the same
number of arguments as the predicate represented. C functions are
provided to analyse the passed terms, convert them to basic C types as
well as to instantiate arguments using unification. Non-deterministic
foreign predicates are supported, providing the foreign function with a
handle to control backtracking.

C can call Prolog predicates, providing both a query interface and
an interface to extract multiple solutions from a non-deterministic
Prolog predicate.  There is no limit to the nesting of Prolog calling
C, calling Prolog, etc.  It is also possible to write the `main' in
C and use Prolog as an embedded logical engine.


\section{Overview of the Interface}		\label{sec:foreignoverview}

A special include file called \file{SWI-Prolog.h} should be included
with each C source file that is to be loaded via the foreign interface.
The installation process installs this file in the directory
\file{include} in the SWI-Prolog home directory (\exam{?-
current_prolog_flag(home, Home).}). This C header file defines various
data types, macros and functions that can be used to communicate with
SWI-Prolog. Functions and macros can be divided into the following
categories:

\begin{shortlist}
    \item Analysing Prolog terms
    \item Constructing new terms
    \item Unifying terms
    \item Returning control information to Prolog
    \item Registering foreign predicates with Prolog
    \item Calling Prolog from C
    \item Recorded database interactions
    \item Global actions on Prolog (halt, break, abort, etc.)
\end{shortlist}


\section{Linking Foreign Modules}		\label{sec:foreignlink}

Foreign modules may be linked to Prolog in two ways. Using
\jargon{static linking}, the extensions, a (short) file defining main()
which attaches the extension calls to Prolog, and the SWI-Prolog kernel
distributed as a C library, are linked together to form a new executable.
Using \jargon{dynamic linking}, the extensions are linked to a shared
library (\fileext{so} file on most Unix systems) or dynamic link library
(\fileext{DLL} file on Microsoft platforms) and loaded into the
running Prolog process.%
    \footnote{The system also contains code to load \fileext{o} files
              directly for some operating systems, notably Unix systems
              using the BSD \file{a.out} executable format. As the number of
              Unix platforms supporting this quickly gets smaller and
              this interface is difficult to port and slow, it is no
              longer described in this manual.  The best alternative
              would be to use the \idx{dld} package on machines that do
	      not have shared libraries.}

\subsection{What linking is provided?}
\label{sec:foreign-linking}

The \jargon{static linking} schema can be used on all versions of
SWI-Prolog. Whether or not dynamic linking is supported can be deduced
from the Prolog flag \prologflag{open_shared_object} (see
current_prolog_flag/2). If this Prolog flag yields \const{true},
open_shared_object/2 and related predicates are defined. See
\secref{shlib} for a suitable high-level interface to these predicates.

\subsection{What kind of loading should I be using?}
\label{sec:foreign-linking-options}

All described approaches have their advantages and disadvantages. Static
linking is portable and allows for debugging on all platforms. It is
relatively cumbersome and the libraries you need to pass to the linker
may vary from system to system, though the utility program
\program{swipl-ld} described in \secref{plld} often hides these problems
from the user.

Loading shared objects (DLL files on Windows) provides sharing and
protection and is generally the best choice. If a saved state is created
using qsave_program/[1,2], an initialization/1 directive may be used to
load the appropriate library at startup.

Note that the definition of the foreign predicates is the same, regardless
of the linking type used.

\input{lib/shlib}

\subsection{Low-level operations on shared libraries}
\label{sec:sharedobj}

The interface defined in this section allows the user to load shared
libraries (\fileext{so} files on most Unix systems, \fileext{dll} files
on Windows). This interface is portable to Windows as well as to Unix
machines providing \manref{dlopen}{2} (Solaris, Linux, FreeBSD, Irix and
many more) or \manref{shl_open}{2} (HP/UX). It is advised to use the
predicates from \secref{shlib} in your application.


\begin{description}
    \predicate{open_shared_object}{2}{+File, -Handle}
\arg{File} is the name of a shared object file (DLL in MS-Windows). This file is attached to the current process, and
\arg{Handle} is unified with a handle to the library. Equivalent to
\exam{open_shared_object(File, Handle, [])}. See also
open_shared_object/3 and load_foreign_library/1.

On errors, an exception \term{shared_object}{Action, Message} is
raised. \arg{Message} is the return value from dlerror().

    \predicate{open_shared_object}{3}{+File, -Handle, +Options}
As open_shared_object/2, but allows for additional flags to be passed.
\arg{Options} is a list of atoms. \const{now} implies the symbols are
resolved immediately rather than lazy (default). \const{global} implies
symbols of the loaded object are visible while loading other shared
objects (by default they are local). Note that these flags may not be
supported by your operating system. Check the documentation of dlopen()
or equivalent on your operating system.  Unsupported flags are silently
ignored.

    \predicate{close_shared_object}{1}{+Handle}
Detach the shared object identified by \arg{Handle}.

    \predicate{call_shared_object_function}{2}{+Handle, +Function}
Call the named function in the loaded shared library.  The function
is called without arguments and the return value is ignored.  Normally
this function installs foreign language predicates using calls to
PL_register_foreign().
\end{description}


\subsection{Static Linking} \label{sec:staticl}

Below is an outline of the file structure required for statically
linking SWI-Prolog with foreign extensions. \file{.../swipl} refers to
the SWI-Prolog home directory (see the Prolog flag \prologflag{home}).
\file{<arch>} refers to the architecture identifier that may be obtained
using the Prolog flag \prologflag{arch}.

\begin{center}
\begin{tabular}{ll}
\file{.../swipl/runtime/<arch>/libswipl.a} & SWI-Library \\
\file{.../swipl/include/SWI-Prolog.h}      & Include file \\
\file{.../swipl/include/SWI-Stream.h}      & Stream I/O include file \\
\file{.../swipl/include/SWI-Exports}       & Export declarations (AIX only) \\
\file{.../swipl/include/stub.c}            & Extension stub
\end{tabular}
\end{center}

The definition of the foreign predicates is the same as for dynamic
linking.  Unlike with dynamic linking, however, there is no
initialisation function.  Instead, the file \file{.../swipl/include/stub.c}
may be copied to your project and modified to define the foreign
extensions.  Below is \file{stub.c}, modified to link the lowercase example
described later in this chapter:

\begin{code}
#include <stdio.h>
#include <SWI-Prolog.h>

extern foreign_t pl_lowercase(term, term);

PL_extension predicates[] =
{
/*{ "name",      arity,  function,      PL_FA_<flags> },*/

  { "lowercase", 2       pl_lowercase,  0 },
  { NULL,        0,      NULL,          0 } /* terminating line */
};


int
main(int argc, char **argv)
{ PL_register_extensions(predicates);

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

  PL_halt(PL_toplevel() ? 0 : 1);
}
\end{code}

Now, a new executable may be created by compiling this file and linking
it to \file{libpl.a} from the runtime directory and the libraries
required by both the extensions and the SWI-Prolog kernel. This may be
done by hand, or by using the \program{swipl-ld} utility described in
\secref{plld}. If the linking is performed by hand, the command line
option \cmdlineoption{--dump-runtime-variables} (see \secref{cmdline})
can be used to obtain the required paths, libraries and linking options
to link the new executable.

\section{Interface Data Types}		\label{sec:foreigntypes}

\subsection{Type \ctype{term_t}: a reference to a Prolog term}
\label{sec:type-term-t}

The principal data type is \ctype{term_t}. Type \ctype{term_t} is what
Quintus calls \ctype{QP_term_ref}. This name indicates better what the
type represents: it is a \jargon{handle} for a term rather than the term
itself. Terms can only be represented and manipulated using this type,
as this is the only safe way to ensure the Prolog kernel is aware of all
terms referenced by foreign code and thus allows the kernel to perform
garbage collection and/or stack-shifts while foreign code is active,
for example during a callback from C.

A term reference is a C unsigned long, representing the offset of a
variable on the Prolog environment stack.  A foreign function is passed
term references for the predicate arguments, one for each argument.  If
references for intermediate results are needed, such references may be
created using PL_new_term_ref() or PL_new_term_refs().  These references
normally live till the foreign function returns control back to Prolog.
Their scope can be explicitly limited using PL_open_foreign_frame()
and PL_close_foreign_frame()/PL_discard_foreign_frame().

A \ctype{term_t} always refers to a valid Prolog term (variable, atom, integer,
float or compound term). A term lives either until backtracking takes us
back to a point before the term was created, the garbage collector has
collected the term, or the term was created after a
PL_open_foreign_frame() and PL_discard_foreign_frame() has been called.

The foreign interface functions can either {\em read}, {\em unify} or
{\em write} to term references.  In this document we use the
following notation for arguments of type \ctype{term_t}:

\begin{quote}
\begin{tabular}{lp{4in}}
\tt term_t +t   & Accessed in read-mode.  The `+' indicates the
                  argument is `input'. \\
\tt term_t -t   & Accessed in write-mode. \\
\tt term_t ?t   & Accessed in unify-mode. \\
\end{tabular}
\end{quote}

\textbf{WARNING} Term references that are accessed in `write' (-) mode
will refer to an invalid term if the term is allocated on the global
stack and backtracking takes us back to a point before the term was
written.\footnote{This could have been avoided by \jargon{trailing} term
references when data is written to them. This seriously hurts
performance in some scenarios though. If this is desired, use
PL_put_variable() followed by one of the PL_unify_*() functions.}
Compounds, large integers, floats and strings are all allocated on the
global stack. Below is a typical scenario where this may happen. The
first solution writes a term extracted from the solution into \arg{a}.
After the system backtracks due to PL_next_solution(), \arg{a} becomes a
reference to a term that no longer exists.

\begin{code}
term_t a = PL_new_term_ref();
...
query = PL_open_query(...);
while(PL_next_solution(query))
{ PL_get_arg(i, ..., a);
}
PL_close_query(query);
\end{code}

There are two solutions to this problem. One is to scope the term
reference using PL_open_foreign_frame() and PL_close_foreign_frame() and
makes sure it goes out of scope before backtracking happens. The other
is to clear the term reference using PL_put_variable() before
backtracking.

Term references are obtained in any of the following ways:

\begin{itemlist}
\item [Passed as argument]
    The C functions implementing foreign predicates are passed their
    arguments as term references.  These references may be read or
    unified.  Writing to these variables causes undefined behaviour.
\item [Created by PL_new_term_ref()]
    A term created by PL_new_term_ref() is normally used to build
    temporary terms or to be written by one of the interface functions.
    For example, PL_get_arg() writes a reference to the term argument
    in its last argument.
\item [Created by PL_new_term_refs(int n)]
    This function returns a set of term references with the same characteristics
    as PL_new_term_ref().  See PL_open_query().
\item [Created by PL_copy_term_ref(term_t t)]
    Creates a new term reference to the same term as the argument.  The
    term may be written to.  See \figref{pl-display}.
\end{itemlist}

Term references can safely be copied to other C variables of type
\ctype{term_t}, but all copies will always refer to the same term.

\begin{description}
\cfunction{term_t}{PL_new_term_ref}{}
Return a fresh reference to a term.  The reference is allocated on the
\jargon{local} stack.  Allocating a term reference may trigger a stack-shift
on machines that cannot use sparse memory management for allocation of the
Prolog stacks.  The returned reference describes a variable.
\cfunction{term_t}{PL_new_term_refs}{int n}
Return \arg{n} new term references.  The first term reference is returned.
The others are $\arg{t}+1$, $\arg{t}+2$, etc.  There are two reasons
for using this function.  PL_open_query() expects the arguments as a set
of consecutive term references, and {\em very} time-critical code requiring
a number of term references can be written as:

\begin{code}
pl_mypredicate(term_t a0, term_t a1)
{ term_t t0 = PL_new_term_refs(2);
  term_t t1 = t0+1;

  ...
}
\end{code}
\cfunction{term_t}{PL_copy_term_ref}{term_t from}
Create a new term reference and make it point initially to the same
term as \arg{from}.  This function is commonly used to copy a predicate
argument to a term reference that may be written.
\cfunction{void}{PL_reset_term_refs}{term_t after}
Destroy all term references that have been created after \arg{after},
including \arg{after} itself. Any reference to the invalidated  term
references after this call results in undefined behaviour.

Note that returning from the foreign context to Prolog will reclaim
all references used in the foreign context.  This call is only necessary
if references are created inside a loop that never exits back to Prolog.
See also PL_open_foreign_frame(), PL_close_foreign_frame() and
PL_discard_foreign_frame().
\end{description}


\subsubsection{Interaction with the garbage collector and stack-shifter}
\label{sec:foreign-gc}

Prolog implements two mechanisms for avoiding stack overflow: garbage
collection and stack expansion. On machines that allow for it, Prolog
will use virtual memory management to detect stack overflow and expand
the runtime stacks. On other machines Prolog will reallocate the stacks
and update all pointers to them. To do so, Prolog needs to know which
data is referenced by C code. As all Prolog data known by C is
referenced through term references (\ctype{term_t}), Prolog has all the
information necessary to perform its memory management without
special precautions from the C programmer.


\subsection{Other foreign interface types}
\label{sec:foreign-types}

\begin{description}
    \item[atom_t]
An atom in Prolog's internal representation.  Atoms are pointers to an
opaque structure.  They are a unique representation for represented
text, which implies that atom $A$ represents the same text as
atom $B$ if and only if $A$ and $B$ are the same pointer.

Atoms are the central representation for textual constants in Prolog.
The transformation of a character string $C$ to an atom implies a
hash-table lookup.  If the same atom is needed often, it is advised
to store its reference in a global variable to avoid repeated lookup.
    \item[functor_t]
A functor is the internal representation of a name/arity pair. They are
used to find the name and arity of a compound term as well as to
construct new compound terms. Like atoms they live for the whole Prolog
session and are unique.
    \item[predicate_t]
Handle to a Prolog predicate. Predicate handles live forever (although
they can lose their definition).
    \item[qid_t]
Query identifier. Used by
PL_open_query(), PL_next_solution() and PL_close_query() to handle
backtracking from C.
    \item[fid_t]
Frame identifier. Used by
PL_open_foreign_frame() and PL_close_foreign_frame().
    \item[module_t]
A module is a unique handle to a Prolog module. Modules are used only
to call predicates in a specific module.
    \item[foreign_t]
Return type for a C function implementing a Prolog predicate.
    \item[control_t]
Passed as additional argument to non-deterministic foreign functions.
See PL_retry*() and PL_foreign_context*().
    \item[install_t]
Type for the install() and uninstall() functions of shared
or dynamic link libraries.  See \secref{shlib}.
    \item[int64_t]
Actually part of the C99 standard rather than Prolog. As of version
5.5.6, Prolog integers are 64-bit on all hardware. The C99 type
\ctype{int64_t} is defined in the \file{stdint.h} standard header and
provides platform-independent 64-bit integers. Portable code accessing
Prolog should use this type to exchange integer values. Please note that
PL_get_long() can return \const{FALSE} on Prolog integers that cannot be
represented as a C long. Robust code should not assume any of the
integer fetching functions to succeed, \emph{even} if the Prolog term is known
to be an integer.
\end{description}

\subsubsection{PL_ARITY_AS_SIZE}
\label{sec:pl-arity-as-size}

As of SWI-Prolog 7.3.12, the arity of terms has changed from \ctype{int}
to \ctype{size_t}. To deal with this transition, all affecting functions
have two versions, where the old name exchanges the arity as \ctype{int}
and a new function with name *_sz() exchanges the arity as
\ctype{size_t}. Op to 8.1.28, the default was to use the old \ctype{int}
functions. As of 8.1.29/8.2.x, the default is to use \ctype{size_t} and
the old behaviour can be restored by defining \const{PL_ARITY_AS_SIZE}
to \const{0} (zero). This makes old code compatible, but the following
warning is printed when compiling:

\begin{code}
#warning "Term arity has changed from int to size_t."
#warning "Please update your code or use #define PL_ARITY_AS_SIZE 0."
\end{code}

To make the code compile silently again, change the types you use to
represent arity from \ctype{int} to \ctype{size_t}. Please be aware that
\ctype{size_t} is \emph{unsigned}.  At some point representing arity
as \ctype{int} will be dropped completely.


\section{The Foreign Include File}	\label{sec:foreigninclude}

\subsection{Argument Passing and Control}
\label{sec:foreign-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, \ldots, <arity>$ pass the Prolog arguments to the goal
as Prolog terms. Foreign functions should be declared of type
\ctype{foreign_t}. Deterministic foreign functions have two alternatives
to return control back to Prolog:

\begin{description}
    \cmacro{(return) foreign_t}{PL_succeed}{}
Succeed deterministically. PL_succeed is defined as
\exam{return \const{TRUE}}.
    \cmacro{(return) foreign_t}{PL_fail}{}
Fail and start Prolog backtracking.  PL_fail is defined as \exam{return
\const{FALSE}}.
\end{description}

\subsubsection{Non-deterministic Foreign Predicates}	\label{sec:foreignnondet}

By default foreign predicates are deterministic. Using the
\const{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:

\begin{code}
quotient_below_n(Q, N) :-
        natural_number_below_n(N, N1),
        natural_number_below_n(N, N2),
        Q =:= N1 / N2, !.
\end{code}

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:

\begin{itemlist}
    \item [Initial call (\const{PL_FIRST_CALL})]
Prolog has just created a frame for the foreign function and asks it to
produce the first answer.
    \item [Redo call (\const{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.
    \item [Terminate call (\const{PL_PRUNED})]
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.
\end{itemlist}

Both the context information and the type of call is provided by an
argument of type \ctype{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 {\tt PL_retry*()} macros and
extract the handle from the extra argument using the
{\tt PL_foreign_context*()} macro.

\begin{description}
    \cmacro{(return) foreign_t}{PL_retry}{intptr_t value}
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 signed value two bits smaller than a pointer,
i.e., 30 or 62 bits (two bits are used for status indication).
Defined as \exam{return _PL_retry(n)}. See also PL_succeed().

    \cmacro{(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 \exam{return _PL_retry_address(n)}. See also
PL_succeed().

    \cmacro{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 \const{PL_PRUNED} case and should be aware that the other
arguments are not valid in this case.

    \cmacro{intptr_t}{PL_foreign_context}{control_t}
Extracts the context from the context argument.  If the call type is
\const{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 \const{PL_REDO} or \const{PL_PRUNED}).

    \cmacro{void *}{PL_foreign_context_address}{control_t}
Extracts an address as passed in by PL_retry_address().

    \cmacro{predicate_t}{PL_foreign_context_predicate}{control_t}

Fetch the Prolog predicate that is executing this function. Note that if
the predicate is imported, the returned predicate refers to the final
definition rather than the imported predicate, i.e., the module reported
by PL_predicate_info() is the module in which the predicate is defined
rather than the module where it was called. See also
PL_predicate_info().
\end{description}

Note: If a non-deterministic foreign function returns using PL_succeed()
or PL_fail(), Prolog assumes the foreign function has cleaned its
environment. {\bf No} call with control argument \const{PL_PRUNED} will
follow.

The code of \figref{nondetermf} shows a skeleton for a
non-deterministic foreign predicate definition.

\begin{figure}
\begin{code}
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_PRUNED:
        ctxt = PL_foreign_context_address(handle);
        ...
        free(ctxt);
        PL_succeed;
  }
}
\end{code}
    \caption{Skeleton for non-deterministic foreign functions}
    \label{fig:nondetermf}
\end{figure}


\subsection{Atoms and functors}
\label{sec:foreign-atoms}

The following functions provide for communication using atoms and
functors.

\begin{description}
    \cfunction{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 \secref{atomgc}).  The following atoms are provided
as macros, giving access to the empty list symbol and the name of the
list constructor.  Prior to version~7, \const{ATOM_nil} is the same
as \exam{PL_new_atom("[]")} and \const{ATOM_dot} is the same as
\exam{PL_new_atom(".")}.  This is no long the case in SWI-Prolog
version~7.

    \begin{description}
	\cmacro{atom_t}{ATOM_nil}
Atomic constant that represents the empty list.  It is advised to
use PL_get_nil(), PL_put_nil() or PL_unify_nil() where applicable.

	\cmacro{atom_t}{ATOM_dot}
Atomic constant that represents the name of the list constructor.
The list constructor itself is created using
\exam{PL_new_functor(ATOM_dot,2)}.   It is advised to use
PL_get_list(), PL_put_list() or PL_unify_list() where applicable.
    \end{description}

    \cfunction{atom_t}{PL_new_atom_mbchars}{int rep, size_t len,
					    const char *s}
This function generalizes PL_new_atom() and PL_new_atom_nchars() while
allowing for multiple encodings. The \arg{rep} argument is one of
\const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. If
\arg{len} is \exam{(size_t)-1}, it is computed from \arg{s} using
strlen().

    \cfunction{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 \secref{atomgc}).  Foreign functions that require
the text from an atom passed in a \ctype{term_t} normally use
PL_get_atom_chars() or PL_get_atom_nchars().

    \cfunction{functor_t}{PL_new_functor}{atom_t name, int arity}
Returns a {\em functor identifier}, a handle for the name/arity
pair.  The returned handle is valid for the entire Prolog session.
\cfunction{atom_t}{PL_functor_name}{functor_t f}
Return an atom representing the name of the given functor.
\cfunction{size_t}{PL_functor_arity}{functor_t f}
Return the arity of the given functor.
\end{description}


\subsubsection{Atoms and atom garbage collection}	\label{sec:atomgc}

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
\jargon{call-port}. In the multithreaded version (see \chapref{threads}),
they appear asynchronously, except for the invoking thread.

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

\begin{description}
    \cfunction{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.%
	\footnote{Otherwise asynchronous atom garbage collection might
		  destroy the atom before it is used.}

    \cfunction{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.
\end{description}

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

\begin{code}
PL_unify_atom_chars(t, "text");
PL_unify_atom(t, PL_new_atom("text"));
\end{code}

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


\subsection{Analysing Terms via the Foreign Interface}
\label{sec:foreign-term-analysis}

Each argument of a foreign function (except for the control argument) is
of type \ctype{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 {\tt PL_is_*()}. The second group attempts to translate the
argument into a C primitive type. These predicates take a \ctype{term_t}
and a pointer to the appropriate C type and return \const{TRUE} or
\const{FALSE} depending on successful or unsuccessful translation. If the
translation fails, the pointed-to data is never modified.

\subsubsection{Testing the type of a term}
\label{sec:foreign-term-type}

\begin{description}
\cfunction{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 {\tt PL_get_*()} also
validate the type and thus the two sections below are
equivalent.

\begin{code}
        if ( PL_is_atom(t) )
        { char *s;

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

or

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

\textbf{Version~7} added \const{PL_NIL}, \const{PL_BLOB},
\const{PL_LIST_PAIR} and \const{PL_DICT}.  Older versions
classify \const{PL_NIL} and \const{PL_BLOB} as \const{PL_ATOM},
\const{PL_LIST_PAIR} as \const{PL_TERM}	and do not have
dicts.

\begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|}
\hline
\const{PL_VARIABLE}  & A variable or attributed variable \\
\const{PL_ATOM}      & A Prolog atom \\
\const{PL_NIL}       & The constant \verb$[]$ \\
\const{PL_BLOB}	     & A blob (see \secref{blobaccess}) \\
\const{PL_STRING}    & A string (see \secref{strings}) \\
\const{PL_INTEGER}   & A integer \\
\const{PL_RATIONAL}  & A rational number \\
\const{PL_FLOAT}     & A floating point number \\
\const{PL_TERM}      & A compound term \\
\const{PL_LIST_PAIR} & A list cell (\verb$[H|T]$) \\
\const{PL_DICT}	     & A dict (see \secref{bidicts})) \\
\hline
\end{tabular}
\end{description}

The functions PL_is_<type> are an alternative to PL_term_type(). The
test \exam{PL_is_variable(term)} is equivalent to
\exam{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 \const{TRUE} or \const{FALSE}.

\begin{description}
    \cfunction{int}{PL_is_variable}{term_t}
Returns non-zero if \arg{term} is a variable.

    \cfunction{int}{PL_is_ground}{term_t}
Returns non-zero if \arg{term} is a ground term.  See also ground/1.
This function is cycle-safe.

    \cfunction{int}{PL_is_atom}{term_t}
Returns non-zero if \arg{term} is an atom.

    \cfunction{int}{PL_is_string}{term_t}
Returns non-zero if \arg{term} is a string.

    \cfunction{int}{PL_is_integer}{term_t}
Returns non-zero if \arg{term} is an integer.

    \cfunction{int}{PL_is_rational}{term_t}
Returns non-zero if \arg{term} is a rational number ($P/Q$).  Note
that all integers are considered rational and this test thus succeeds
for any term for which PL_is_integer() succeeds.  See also
PL_get_mpq() and PL_unify_mpq().

    \cfunction{int}{PL_is_float}{term_t}
Returns non-zero if \arg{term} is a float. Note that the corresponding
PL_get_float() converts rationals (and thus integers).

    \cfunction{int}{PL_is_callable}{term_t}
Returns non-zero if \arg{term} is a callable term.  See callable/1
for details.

    \cfunction{int}{PL_is_compound}{term_t}
Returns non-zero if \arg{term} is a compound term.

    \cfunction{int}{PL_is_functor}{term_t, functor_t}
Returns non-zero if \arg{term} is compound and its functor is \arg{functor}.
This test is equivalent to PL_get_functor(), followed by testing the
functor, but easier to write and faster.

    \cfunction{int}{PL_is_list}{term_t}
Returns non-zero if \arg{term} is a compound term using the list
constructor or the list terminator. See also PL_is_pair() and
PL_skip_list().

    \cfunction{int}{PL_is_pair}{term_t}
Returns non-zero if \arg{term} is a compound term using the list
constructor.  See also PL_is_list() and PL_skip_list().

    \cfunction{int}{PL_is_dict}{term_t}
Returns non-zero if \arg{term} is a dict.  See also PL_put_dict()
and PL_get_dict_key().

    \cfunction{int}{PL_is_atomic}{term_t}
Returns non-zero if \arg{term} is atomic (not a variable or compound).

    \cfunction{int}{PL_is_number}{term_t}
Returns non-zero if \arg{term} is an rational (including integers) or
float.

    \cfunction{int}{PL_is_acyclic}{term_t}
Returns non-zero if \arg{term} is acyclic (i.e.\ a finite tree).
\end{description}


\subsubsection{Reading data from a term}
\label{sec:foreign-extract-from-term}

The functions {\tt 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.

\begin{description}
    \cfunction{int}{PL_get_atom}{term_t +t, atom_t *a}
If \arg{t} is an atom, store the unique atom identifier over \arg{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 \arg{t}, it
will live at least as long as \arg{t} does.  If longer live-time is
required, the atom should be locked using PL_register_atom().

    \cfunction{int}{PL_get_atom_chars}{term_t +t, char **s}
If \arg{t} is an atom, store a pointer to a 0-terminated C-string in
\arg{s}.  It is explicitly \strong{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.

    \cfunction{int}{PL_get_string_chars}{term_t +t, char **s, size_t *len}
If \arg{t} is a string object, store a pointer to a 0-terminated
C-string in \arg{s} and the length of the string in \arg{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.

    \cfunction{int}{PL_get_chars}{term_t +t, char **s, unsigned flags}
Convert the argument term \arg{t} to a 0-terminated C-string.
\arg{flags} is a bitwise disjunction from two groups of constants. The
first specifies which term types should be converted and the second how
the argument is stored. Below is a specification of these constants.
\const{BUF_STACK} implies, if the data is not static (as from an atom),
that the data is pushed on a stack. If BUF_MALLOC is used, the data must
be freed using PL_free() when no longer needed.

With the introduction of wide characters (see \secref{encoding}), not
all atoms can be converted into a \ctype{char*}.  This function fails
if \arg{t} is of the wrong type, but also if the text cannot be
represented.  See the \const{REP_*} flags below for details.

\begin{description}
    \termitem{CVT_ATOM}{}
Convert if term is an atom.

    \termitem{CVT_STRING}{}
Convert if term is a string.

    \termitem{CVT_LIST}{}
Convert if term is a list of of character codes.

    \termitem{CVT_INTEGER}{}
Convert if term is an integer.

    \termitem{CVT_FLOAT}{}
Convert if term is a float.  The characters returned are the same as
write/1 would write for the floating point number.

    \termitem{CVT_NUMBER}{}
Convert if term is an integer or float.

    \termitem{CVT_ATOMIC}{}
Convert if term is atomic.

    \termitem{CVT_VARIABLE}{}
Convert variable to print-name

    \termitem{CVT_WRITE}{}
Convert any term that is not converted by any of the other flags using
write/1. If no \const{BUF_*} is provided, \const{BUF_STACK} is implied.

    \termitem{CVT_WRITE_CANONICAL}{}
As \const{CVT_WRITE}, but using write_canonical/2.

    \termitem{CVT_WRITEQ}{}
As \const{CVT_WRITE}, but using writeq/2.

    \termitem{CVT_ALL}{}
Convert if term is any of the above, except for \const{CVT_VARIABLE} and
\const{CVT_WRITE*}.

    \termitem{CVT_EXCEPTION}{}
If conversion fails due to a type error, raise a Prolog type error
exception in addition to failure

    \termitem{BUF_DISCARDABLE}{}
Data must copied immediately

    \termitem{BUF_STACK}{}
Data is stored on a stack.  The older \const{BUF_RING} is an alias
for \const{BUF_STACK}.  See \secref{foreign-strings}.

    \termitem{BUF_MALLOC}{}
Data is copied to a new buffer returned by \manref{PL_malloc}{3}. When
no longer needed the user must call PL_free() on the data.

    \termitem{REP_ISO_LATIN_1}{}
Text is in ISO Latin-1 encoding and the call fails if text
cannot be represented.  This flag has the value 0 and is thus the
default.

    \termitem{REP_UTF8}{}
Convert the text to a UTF-8 string. This works for all text.

    \termitem{REP_MB}{}
Convert to default locale-defined 8-bit string. Success depends on the
locale. Conversion is done using the wcrtomb() C library function.
\end{description}


\cfunction{int}{PL_get_list_chars}{+term_t l, char **s, unsigned flags}
Same as \exam{PL_get_chars(\arg{l}, \arg{s}, CVT_LIST|\arg{flags})},
provided \arg{flags} contains none of the {\tt CVT_*} flags.
\cfunction{int}{PL_get_integer}{+term_t t, int *i}
If \arg{t} is a Prolog integer, assign its value over \arg{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().

\cfunction{int}{PL_get_long}{term_t +t, long *i}
If \arg{t} is a Prolog integer that can be represented as a long, assign
its value over \arg{i}. If \arg{t} is an integer that cannot be
represented by a C long, this function returns \const{FALSE}. If \arg{t}
is a floating point number that can be represented as a long, this
function succeeds as well.  See also PL_get_int64().

\cfunction{int}{PL_get_int64}{term_t +t, int64_t *i}
If \arg{t} is a Prolog integer or float that can be represented as a
\ctype{int64_t}, assign its value over \arg{i}.

\cfunction{int}{PL_get_intptr}{term_t +t, intptr_t *i}
Get an integer that is at least as wide as a pointer. On most
platforms this is the same as PL_get_long(), but on Win64 pointers are 8
bytes and longs only 4. Unlike PL_get_pointer(), the value is not
modified.

\cfunction{int}{PL_get_bool}{term_t +t, int *val}
If \arg{t} has the value \const{true} or \const{false}, set \arg{val}
to the C constant \const{TRUE} or \const{FALSE} and return success,
otherwise return failure.
\cfunction{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() and PL_get_pointer()
guarantee pointers in the range of malloc() are handled without
truncating.

\cfunction{int}{PL_get_float}{term_t +t, double *f}
If \arg{t} is a float, integer or rational number, its value is assigned
over \arg{f}. Note that if \arg{t} is an integer or rational conversion
may fail because the number cannot be represented as a float.

\cfunction{int}{PL_get_functor}{term_t +t, functor_t *f}
If \arg{t} is compound or an atom, the Prolog representation of the
name-arity pair will be assigned over \arg{f}. See also
PL_get_name_arity() and PL_is_functor().

\cfunction{int}{PL_get_name_arity}{term_t +t, atom_t *name, size_t *arity}
If \arg{t} is compound or an atom, the functor name will be assigned
over \arg{name} and the arity over \arg{arity}. See also
PL_get_functor() and PL_is_functor().  See \secref{pl-arity-as-size}.

\cfunction{int}{PL_get_compound_name_arity}{term_t +t, atom_t *name, size_t *arity}
If \arg{t} is compound term, the functor name will be assigned over
\arg{name} and the arity over \arg{arity}.  This is the same as
PL_get_name_arity(), but this function fails if \arg{t} is an atom.

\cfunction{int}{PL_get_module}{term_t +t, module_t *module}
If \arg{t} is an atom, the system will look up or create the
corresponding module and assign an opaque pointer to it over {\em
module}.

\cfunction{int}{PL_get_arg}{size_t index, term_t +t, term_t -a}
If \arg{t} is compound and index is between 1 and arity (inclusive),
assign \arg{a} with a term reference to the argument.

\cfunction{int}{_PL_get_arg}{size_t index, term_t +t, term_t -a}
Same as PL_get_arg(), but no checking is performed, neither whether \arg{t}
is actually a term nor whether \arg{index} is a valid argument index.

\cfunction{int}{PL_get_dict_key}{atom_t key, term_t +dict, term_t -value}
If \arg{dict} is a dict, get the associated value in \arg{value}. Fails
silently if \arg{key} does not appear in \arg{dict} and with an
exception if \arg{dict} is not a dict.
\end{description}


\subsubsection{Exchanging text using length and string}
\label{sec:foreign-text-with-length}

All internal text representation in SWI-Prolog is represented using
\type{char *} plus length and allow for \jargon{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.

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

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

\begin{description}
    \cfunction{atom_t}{PL_new_atom_nchars}{size_t len, const char *s}
Create a new atom as PL_new_atom(), but using the given length and characters.
If \arg{len} is \exam{(size_t)-1}, it is computed from \arg{s} using
strlen().

    \cfunction{const char *}{PL_atom_nchars}{atom_t a, size_t *len}
Extract the text and length of an atom.
\end{description}


\subsubsection{Wide-character versions}
\label{sec:foreign-unicode}

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 \ctype{pl_wchar_t}, which is guaranteed to
be the same as \ctype{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.

\begin{description}
    \cfunction{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 \arg{s} only contains ISO-Latin-1 characters a
normal byte-array atom is created. If \arg{len} is \exam{(size_t)-1}, it
is computed from \arg{s} using wcslen().

    \cfunction{pl_wchar_t*}{PL_atom_wchars}{atom_t atom, int *len}
Extract characters from a wide-character atom.  Succeeds on any atom
marked as `text'.  If the underlying atom is a wide-character atom,
the returned pointer is a pointer into the atom structure.  If it is
an ISO-Latin-1 character, the returned pointer comes from Prolog's
`buffer ring' (see PL_get_chars()).

    \cfunction{int}{PL_get_wchars}{term_t t, size_t *len,
				   pl_wchar_t **s, unsigned flags}
Wide-character version of PL_get_chars().  The \arg{flags} argument
is the same as for PL_get_chars().

    \cfunction{int}{PL_unify_wchars}{term_t t, int type,
				     size_t len,
				     const pl_wchar_t *s}
Unify \arg{t} with a textual representation of the C wide-character
array \arg{s}.  The \arg{type} argument defines the Prolog
representation and is one of \const{PL_ATOM}, \const{PL_STRING},
\const{PL_CODE_LIST} or \const{PL_CHAR_LIST}.
    \cfunction{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 \const{PL_CODE_LIST} and \const{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 \file{packages/clib/readutil.c} from the
source distribution.
\end{description}


\subsubsection{Reading a list}
\label{sec:foreign-read-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:

\begin{code}
foreign_t
pl_write_atoms(term_t l)
{ term_t head = PL_new_term_ref();   /* the elements */
  term_t list = PL_copy_term_ref(l); /* copy (we modify list) */

  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 [] */
}
\end{code}

Note that as of version~7, lists have a new representation unless the
option \cmdlineoption{--traditional} is used.  see \secref{ext-lists}.

\begin{description}
    \cfunction{int}{PL_get_list}{term_t +l, term_t -h, term_t -t}
If \arg{l} is a list and not the empty list, assign a term reference to
the head to \arg{h} and to the tail to \arg{t}.

    \cfunction{int}{PL_get_head}{term_t +l, term_t -h}
If \arg{l} is a list and not the empty list, assign a term reference to
the head to \arg{h}.

    \cfunction{int}{PL_get_tail}{term_t +l, term_t -t}
If \arg{l} is a list and not the empty list, assign a term reference to
the tail to \arg{t}.

    \cfunction{int}{PL_get_nil}{term_t +l}
Succeeds if \arg{l} represents the list termination constant.

    \cfunction{int}{PL_skip_list}{term_t +list, term_t -tail, size_t *len}
This is a multi-purpose function to deal with lists.  It allows for
finding the length of a list, checking whether something is a list,
etc. The reference \arg{tail} is set to point to the end of the list,
\arg{len} is filled with the number of list-cells skipped, and the
return value indicates the status of the list:

    \begin{description}
	\constitem{PL_LIST}
    The list is a `proper' list: one that ends in the list terminator
    constant and \arg{tail} is filled with the terminator constant.

	\constitem{PL_PARTIAL_LIST}
    The list is a `partial' list: one that ends in a variable and
    \arg{tail} is a reference to this variable.

	\constitem{PL_CYCLIC_TERM}
    The list is cyclic (e.g. X = [a|X]).  \arg{tail} points to
    an arbitrary cell of the list and \arg{len} is at most twice
    the cycle length of the list.

	\constitem{PL_NOT_A_LIST}
    The term \arg{list} is not a list at all.  \arg{tail} is
    bound to the non-list term and \arg{len} is set to the number
    of list-cells skipped.
    \end{description}

It is allowed to pass 0 for \arg{tail} and \const{NULL} for \arg{len}.
\end{description}

\subsubsection{An example: defining write/1 in C}
\label{sec:foreign-write}

\Figref{pl-display} 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.

\begin{figure}
\begin{code}
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;
}
\end{code}

    \caption{A Foreign definition of display/1}
    \label{fig:pl-display}
\end{figure}


\subsection{Constructing Terms}
\label{sec:foreign-term-construct}

Terms can be constructed using functions from the {\tt PL_put_*()} and
{\tt 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().

\begin{description}
\cfunction{void}{PL_put_variable}{term_t -t}
Put a fresh variable in the term, resetting the term reference to its
initial state.\footnote{Older versions created a variable on the global
stack.}
\cfunction{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().
\cfunction{void}{PL_put_bool}{term_t -t, int val}
Put one of the atoms \const{true} or \const{false} in the term reference
See also PL_put_atom(), PL_unify_bool() and PL_get_bool().
\cfunction{int}{PL_put_chars}{term_t -t, int flags,
			      size_t len,
			      const char *chars}
New function to deal with setting a term from a \ctype{char*} with
various encodings. The \arg{flags} argument is a bitwise \emph{or}
specifying the Prolog target type and the encoding of \arg{chars}. A
Prolog type is one of \const{PL_ATOM}, \const{PL_STRING},
\const{PL_CODE_LIST} or \const{PL_CHAR_LIST}. A representation is one of
\const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. See
PL_get_chars() for a definition of the representation types. If
\arg{len} is \const{-1} \arg{chars} must be zero-terminated and the
length is computed from \arg{chars} using strlen().
\cfunction{int}{PL_put_atom_chars}{term_t -t, const char *chars}
Put an atom in the term reference constructed from the zero-terminated
string.  The string itself will never be referenced by Prolog after this
function.
\cfunction{int}{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().
\cfunction{int}{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 \secref{foreigndata}.
\cfunction{int}{PL_put_list_chars}{term_t -t, const char *chars}
Put a list of ASCII values in the term reference.
\cfunction{int}{PL_put_integer}{term_t -t, long i}
Put a Prolog integer in the term reference.
\cfunction{int}{PL_put_int64}{term_t -t, int64_t i}
Put a Prolog integer in the term reference.
\cfunction{int}{PL_put_uint64}{term_t -t, uint64_t i}
Put a Prolog integer in the term reference.  Note that unbounded integer
support is required for \ctype{uint64_t} values with the highest bit set
to 1.  Without unbounded integer support, too large values raise a
\const{representation_error} exception.
\cfunction{int}{PL_put_pointer}{term_t -t, void *ptr}
Put a Prolog integer in the term reference.  Provided \arg{ptr} is in the
`malloc()-area', PL_get_pointer() will get the pointer back.
\cfunction{int}{PL_put_float}{term_t -t, double f}
Put a floating-point value in the term reference.

    \cfunction{int}{PL_put_functor}{term_t -t, functor_t functor}
Create a new compound term from \arg{functor} and bind \arg{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 {\tt PL_unify_*()} functions or use PL_cons_functor().

    \cfunction{int}{PL_put_list}{term_t -l}
As PL_put_functor(), using the list-cell functor. Note that on classical
Prolog systems or in SWI-Prolog using the option
\cmdlineoption{--traditional}, this is \functor{.}{2}, while on
SWI-Prolog version~7 this is \functor{[|]}{2}.

    \cfunction{int}{PL_put_nil}{term_t -l}
Put the list terminator constant in \arg{l}. Always returns
\const{TRUE}. Note that in classical Prolog systems or in SWI-Prolog
using the option \cmdlineoption{--traditional}, this is the same as
\exam{PL_put_atom_chars("[]")}. See \secref{ext-lists}.

    \cfunction{void}{PL_put_term}{term_t -t1, term_t +t2}
Make \arg{t1} point to the same term as \arg{t2}.

    \cfunction{int}{PL_cons_functor}{term_t -h, functor_t f, \ldots}
Create a term whose arguments are filled from a variable argument list
holding the same number of \ctype{term_t} objects as the arity of the functor.
To create the term \exam{animal(gnu, 50)}, use:

\begin{code}
{ 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);
}
\end{code}


After this sequence, the term references \arg{a1} and \arg{a2} may
be used for other purposes.
\cfunction{int}{PL_cons_functor_v}{term_t -h, functor_t f, term_t a0}
Create a compound term like PL_cons_functor(), but \arg{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.
\cfunction{int}{PL_cons_list}{term_t -l, term_t +h, term_t +t}
Create a list (cons-) cell in \arg{l} from the head \arg{h} and tail \arg{t}.  The
code below creates a list of atoms from a \ctype{char **}.  The list
is built tail-to-head.  The {\tt PL_unify_*()} functions can be used
to build a list head-to-tail.

\begin{code}
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);
  }
}
\end{code}
Note that \arg{l} can be redefined within a {\tt PL_cons_list} call as
shown here because operationally its old value is consumed before its
new value is set.

\cfunction{int}{PL_put_dict}{term_t -h, atom_t tag, size_t len,
			     const atom_t *keys, term_t values}
Create a dict from a \arg{tag} and vector of atom-value pairs and put
the result in \arg{h}.  The dict's key is set by \arg{tag}, which may
be \const{0} to leave the tag unbound. The \arg{keys} vector is a vector
of atoms of at least \arg{len} long. The \arg{values} is a term vector
allocated using PL_new_term_refs() of at least \arg{len} long. This
function returns \const{TRUE} on success, \const{FALSE} on a resource
error (leaving a resource error exception in the environment),
\const{-1} if some key or the \arg{tag} is invalid and \const{-2} if
there are duplicate keys.
\end{description}


\subsection{Unifying data}
\label{sec:foreign-unify}

The functions of this section \jargon{unify} terms with other terms or
translated C data structures. Except for PL_unify(), these functions
are specific to SWI-Prolog. They have been introduced
because they shorten the code for returning data to Prolog and at the
same time make this more efficient by avoiding the need to allocate
temporary term references and reduce the number of calls to the Prolog
API. Consider the case where we want a foreign function to return the
host name of the machine Prolog is running on. Using the {\tt
PL_get_*()} and {\tt PL_put_*()} functions, the code becomes:

\begin{code}
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;
}
\end{code}

Using PL_unify_atom_chars(), this becomes:

\begin{code}
foreign_t
pl_hostname(term_t name)
{ char buf[100];

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

  PL_fail;
}
\end{code}

Note that unification functions that perform multiple bindings may leave
part of the bindings in case of failure. See PL_unify() for details.


\begin{description}
    \cfunction{int}{PL_unify}{term_t ?t1, term_t ?t2}
Unify two Prolog terms and return \const{TRUE} on success.

Care is needed if PL_unify() returns \const{FAIL} and the foreign
function does not \emph{immediately} return to Prolog with \const{FAIL}.
Unification may perform multiple changes to either \arg{t1} or \arg{t2}.
A failing unification may have created bindings before failure is
detected. \emph{Already created bindings are not undone}. For
example, calling PL_unify() on \term{a}{X, a} and \term{a}{c,b} binds
\arg{X} to \const{c} and fails when trying to unify \const{a} to
\const{b}. If control remains in C or even if we want to return success
to Prolog, we \emph{must} undo such bindings. This is achieved using
PL_open_foreign_frame() and PL_rewind_foreign_frame(), as shown in the
snippet below.

\begin{code}
    { fid_t fid = PL_open_foreign_frame();

      ...
      if ( !PL_unify(t1, t2) )
        PL_rewind_foreign_frame(fid);
      ...

      PL_close_foreign_frame(fid);
    }
\end{code}

In addition, PL_unify() may have failed on an \textbf{exception},
typically a resource (stack) overflow. This can be tested using
PL_exception(), passing 0 (zero) for the query-id argument. Foreign
functions that encounter an exception must return \const{FAIL} to
Prolog as soon as possible or call PL_clear_exception() if they wish
to ignore the exception.

    \cfunction{int}{PL_unify_atom}{term_t ?t, atom_t a}
Unify \arg{t} with the atom \arg{a} and return non-zero on success.

    \cfunction{int}{PL_unify_bool}{term_t ?t, int a}
Unify \arg{t} with either \const{true} or \const{false}.

    \cfunction{int}{PL_unify_chars}{term_t ?t, int flags,
				    size_t len,
				    const char *chars}
New function to deal with unification of \ctype{char*} with various
encodings to a Prolog representation. The \arg{flags} argument is a
bitwise \emph{or} specifying the Prolog target type and the encoding of
\arg{chars}. A Prolog type is one of \const{PL_ATOM}, \const{PL_STRING},
\const{PL_CODE_LIST} or \const{PL_CHAR_LIST}. A representation is one of
\const{REP_ISO_LATIN_1}, \const{REP_UTF8} or \const{REP_MB}. See
PL_get_chars() for a definition of the representation types. If
\arg{len} is \const{-1} \arg{chars} must be zero-terminated and the length
is computed from \arg{chars} using strlen().

If \arg{flags} includes \const{PL_DIFF_LIST} and type is one of
\const{PL_CODE_LIST} or \const{PL_CHAR_LIST}, the text is converted
to a \jargon{difference list}.  The tail of the difference list is
$t+1$.

    \cfunction{int}{PL_unify_atom_chars}{term_t ?t, const char *chars}
Unify \arg{t} with an atom created from \arg{chars}  and return non-zero
on success.

    \cfunction{int}{PL_unify_list_chars}{term_t ?t, const char *chars}
Unify \arg{t} with a list of ASCII characters constructed from
\arg{chars}.

    \cfunction{void}{PL_unify_string_chars}{term_t ?t, const char *chars}
Unify \arg{t} with a Prolog string object created from the
zero-terminated string \arg{chars}. The data will be copied.
See also PL_unify_string_nchars().
    \cfunction{int}{PL_unify_integer}{term_t ?t, intptr_t n}
Unify \arg{t} with a Prolog integer from \arg{n}.
    \cfunction{int}{PL_unify_int64}{term_t ?t, int64_t n}
Unify \arg{t} with a Prolog integer from \arg{n}.
    \cfunction{int}{PL_unify_uint64}{term_t ?t, uint64_t n}
Unify \arg{t} with a Prolog integer from \arg{n}.  Note that unbounded
integer support is required if \arg{n} does not fit in a \emph{signed}
\ctype{int64_t}.  If unbounded integers are not supported a
\const{representation_error} is raised.
    \cfunction{int}{PL_unify_float}{term_t ?t, double f}
Unify \arg{t} with a Prolog float from \arg{f}.
    \cfunction{int}{PL_unify_pointer}{term_t ?t, void *ptr}
Unify \arg{t} with a Prolog integer describing the pointer. See also
PL_put_pointer() and PL_get_pointer().

    \cfunction{int}{PL_unify_functor}{term_t ?t, functor_t f}
If \arg{t} is a compound term with the given functor, just succeed.
If it is unbound, create a term and bind the variable, else fail.
Note that this function does not create a term if the argument is
already instantiated.  If \arg{f} is a functor with arity 0, \arg{t}
is unified with an atom.  See also PL_unify_compound().

    \cfunction{int}{PL_unify_compound}{term_t ?t, functor_t f}
If \arg{t} is a compound term with the given functor, just succeed.
If it is unbound, create a term and bind the variable, else fail.
Note that this function does not create a term if the argument is
already instantiated.  If \arg{f} is a functor with arity 0, \arg{t}
is unified with compound without arguments. See also
PL_unify_functor().

    \cfunction{int}{PL_unify_list}{term_t ?l, term_t -h, term_t -t}
Unify \arg{l} with a list-cell ({\tt ./2}). If successful, write a
reference to the head of the list into \arg{h} and a reference
to the tail of the list into \arg{t}. This reference may be used for
subsequent calls to this function. Suppose we want to return a list of
atoms from a \ctype{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.

\begin{code}
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);
}
\end{code}
\cfunction{int}{PL_unify_nil}{term_t ?l}
Unify \arg{l} with the atom \const{[]}.
\cfunction{int}{PL_unify_arg}{int index, term_t ?t, term_t ?a}
Unifies the {\em index-th} argument (1-based) of \arg{t} with
\arg{a}.
\cfunction{int}{PL_unify_term}{term_t ?t, \ldots}
Unify \arg{t} with a (normally) compound term.  The remaining arguments
are 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 \type{int} to \type{int}. That is, the types
\type{char}, \type{short} and \type{int} are all passed as \type{int}.
In addition, on most 32-bit platforms \type{int} and \type{long} are the
same. Up to version 4.0.5, only \const{PL_INTEGER} could be specified,
which was taken from the stack as \type{long}. Such code fails when
passing small integral types on machines where \type{int} is smaller
than \type{long}. It is advised to use \const{PL_SHORT}, \const{PL_INT}
or \const{PL_LONG} as appropriate. Similarly, C compilers promote
\type{float} to \type{double} and therefore \const{PL_FLOAT} and
\const{PL_DOUBLE} are synonyms.

The type identifiers are:

\begin{description}
   \definition{\const{PL_VARIABLE} \arg{none}}
No op.  Used in arguments of \const{PL_FUNCTOR}.
   \definition{\const{PL_BOOL} \arg{int}}
Unify the argument with \const{true} or \const{false}.
   \definition{\const{PL_ATOM} \arg{atom_t}}
Unify the argument with an atom, as in PL_unify_atom().
   \definition{\const{PL_CHARS} \arg{const char *}}
Unify the argument with an atom constructed from the C \ctype{char *},
as in PL_unify_atom_chars().
   \definition{\const{PL_NCHARS} \arg{size_t, const char *}}
Unify the argument with an atom constructed from length and
\ctype{char*} as in PL_unify_atom_nchars().
   \definition{\const{PL_UTF8_CHARS} \arg{const char *}}
Create an atom from a UTF-8 string.
   \definition{\const{PL_UTF8_STRING} \arg{const char *}}
Create a packed string object from a UTF-8 string.
   \definition{\const{PL_MBCHARS} \arg{const char *}}
Create an atom from a multi-byte string in the current locale.
   \definition{\const{PL_MBCODES} \arg{const char *}}
Create a list of character codes from a multi-byte string in the current
locale.
   \definition{\const{PL_MBSTRING} \arg{const char *}}
Create a packed string object from a multi-byte string in the
current locale.
   \definition{\const{PL_NWCHARS} \arg{size_t, const wchar_t *}}
Create an atom from a length and a wide character pointer.
   \definition{\const{PL_NWCODES} \arg{size_t, const wchar_t *}}
Create a list of character codes from a length and a wide character pointer.
   \definition{\const{PL_NWSTRING} \arg{size_t, const wchar_t *}}
Create a packed string object from a length and a wide character pointer.
   \definition{\const{PL_SHORT} \arg{short}}
Unify the argument with an integer, as in PL_unify_integer(). As
\type{short} is promoted to \type{int}, \const{PL_SHORT} is a
synonym for \type{PL_INT}.
   \definition{\const{PL_INTEGER} \arg{long}}
Unify the argument with an integer, as in PL_unify_integer().
   \definition{\const{PL_INT} \arg{int}}
Unify the argument with an integer, as in PL_unify_integer().
   \definition{\const{PL_LONG} \arg{long}}
Unify the argument with an integer, as in PL_unify_integer().
   \definition{\const{PL_INT64} \arg{int64_t}}
Unify the argument with a 64-bit integer, as in PL_unify_int64().
   \definition{\const{PL_INTPTR} \arg{intptr_t}}
Unify the argument with an integer with the same width as a pointer.
On most machines this is the same as \const{PL_LONG}. but on 64-bit
MS-Windows pointers are 64 bits while longs are only 32 bits.
   \definition{\const{PL_DOUBLE} \arg{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.
   \definition{\const{PL_FLOAT} \arg{double}}
Unify the argument with a float, as in PL_unify_float().
   \definition{\const{PL_POINTER} \arg{void *}}
Unify the argument with a pointer, as in PL_unify_pointer().
   \definition{\const{PL_STRING} \arg{const char *}}
Unify the argument with a string object, as in PL_unify_string_chars().
   \definition{\const{PL_TERM} \arg{term_t}}
Unify a subterm.  Note this may be the return value of a PL_new_term_ref()
call to get access to a variable.
   \definition{\const{PL_FUNCTOR} \arg{functor_t, \ldots}}
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.
   \definition{\const{PL_FUNCTOR_CHARS}
	       \arg{const char *name, int arity, \ldots}}
Create a functor from the given name and arity and then behave as
\const{PL_FUNCTOR}.
   \definition{\const{PL_LIST} \arg{int length, \ldots}}
Create a list of the indicated length.  The remaining arguments contain
the elements of the list.
\end{description}

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


\begin{code}
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();
}
\end{code}

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

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

\begin{code}
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)");
  ...
\end{code}

PL_chars_to_term() is defined using PL_put_term_from_chars() which can
deal with not null-terminated strings as well as strings using different
encodings:

\begin{code}
int
PL_chars_to_term(const char *s, term_t t)
{ return PL_put_term_from_chars(t, REP_ISO_LATIN_1, (size_t)-1, s);
}
\end{code}


\cfunction{int}{PL_wchars_to_term}{const pl_wchar_t *chars, term_t -t}
Wide character version of PL_chars_to_term().

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

    In the current implementation, the string is surrounded by
    \arg{chr} and any occurrence of \arg{chr} is doubled.  In the
    future the behaviour will depend on the
    \prologflag{character_escapes} Prolog flag.
\end{description}


\subsection{Convenient functions to generate Prolog exceptions}
\label{sec:cerror}

The typical implementation of a foreign predicate first uses the
PL_get_*() functions to extract C data types from the Prolog terms.
Failure of any of these functions is normally because the Prolog
term is of the wrong type.  The *_ex() family of functions are
wrappers around (mostly) the PL_get_*() functions, such that we
can write code in the style below and get proper exceptions if
an argument is uninstantiated or of the wrong type.

\begin{code}
/** set_size(+Name:atom, +Width:int, +Height:int) is det.

static foreign_t
set_size(term_t name, term_t width, term_t height)
{ char *n;
  int w, h;

  if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) ||
       !PL_get_integer_ex(with, &w) ||
       !PL_get_integer_ex(height, &h) )
    return FALSE;

  ...

}
\end{code}

\begin{description}
    \cfunction{int}{PL_get_atom_ex}{term_t t, atom_t *a}
As PL_get_atom(), but raises a type or instantiation error if
\arg{t} is not an atom.

    \cfunction{int}{PL_get_integer_ex}{term_t t, int *i}
As PL_get_integer(), but raises a type or instantiation error if
\arg{t} is not an integer, or a representation error if the Prolog
integer does not fit in a C \ctype{int}.

    \cfunction{int}{PL_get_long_ex}{term_t t, long *i}
As PL_get_long(), but raises a type or instantiation error if
\arg{t} is not an atom, or a representation error if the Prolog
integer does not fit in a C \ctype{long}.

    \cfunction{int}{PL_get_int64_ex}{term_t t, int64_t *i}
As PL_get_int64(), but raises a type or instantiation error if
\arg{t} is not an atom, or a representation error if the Prolog
integer does not fit in a C \ctype{int64_t}.

    \cfunction{int}{PL_get_intptr_ex}{term_t t, intptr_t *i}
As PL_get_intptr(), but raises a type or instantiation error if
\arg{t} is not an atom, or a representation error if the Prolog
integer does not fit in a C \ctype{intptr_t}.

    \cfunction{int}{PL_get_size_ex}{term_t t, size_t *i}
As PL_get_size(), but raises a type or instantiation error if
\arg{t} is not an atom, or a representation error if the Prolog
integer does not fit in a C \ctype{size_t}.

    \cfunction{int}{PL_get_bool_ex}{term_t t, int *i}
As PL_get_bool(), but raises a type or instantiation error if
\arg{t} is not an boolean.

    \cfunction{int}{PL_get_float_ex}{term_t t, double *f}
As PL_get_float(), but raises a type or instantiation error if
\arg{t} is not a float.

    \cfunction{int}{PL_get_char_ex}{term_t t, int *p, int eof}
Get a character code from \arg{t}, where \arg{t} is either an
integer or an atom with length one.  If \arg{eof} is \const{TRUE}
and \arg{t} is -1, \arg{p} is filled with -1.  Raises an appropriate
error if the conversion is not possible.

    \cfunction{int}{PL_get_pointer_ex}{term_t t, void **addrp}
As PL_get_pointer(), but raises a type or instantiation error if
\arg{t} is not a pointer.

    \cfunction{int}{PL_get_list_ex}{term_t l, term_t h, term_t t}
As PL_get_list(), but raises a type or instantiation error if
\arg{t} is not a list.

    \cfunction{int}{PL_get_nil_ex}{term_t l}
As PL_get_nil(), but raises a type or instantiation error if
\arg{t} is not the empty list.

    \cfunction{int}{PL_unify_list_ex}{term_t l, term_t h, term_t t}
As PL_unify_list(), but raises a type error if \arg{t} is not a
variable, list-cell or the empty list.

    \cfunction{int}{PL_unify_nil_ex}{term_t l}
As PL_unify_nil(), but raises a type error if \arg{t} is not a
variable, list-cell or the empty list.

    \cfunction{int}{PL_unify_bool_ex}{term_t t, int val}
As PL_unify_bool(), but raises a type error if \arg{t} is not a
variable or a boolean.
\end{description}

The second family of functions in this section simplifies the generation
of ISO compatible error terms. Any foreign function that calls this
function must return to Prolog with the return code of the error
function or the constant \const{FALSE}. If available, these error
functions add the name of the calling predicate to the error context.
See also PL_raise_exception().

\begin{description}
    \cfunction{int}{PL_instantiation_error}{term_t culprit}
Raise \const{instantiation_error}.  \arg{Culprit} is ignored, but
should be bound to the term that is insufficiently instantiated.  See
instantiation_error/1.

    \cfunction{int}{PL_uninstantiation_error}{term_t culprit}
Raise \exam{uninstantiation_error(culprit)}. This should be called if an
argument that must be unbound at entry is bound to \arg{culprit}. This
error is typically raised for a pure output arguments such as a newly
created stream handle (e.g., the third argument of open/3).

    \cfunction{int}{PL_representation_error}{const char *resource}
Raise \exam{representation_error(resource)}. See representation_error/1.

    \cfunction{int}{PL_type_error}{const char *expected, term_t culprit}
Raise \exam{type_error(expected, culprit)}.  See type_error/2.

    \cfunction{int}{PL_domain_error}{const char *expected, term_t culprit}
Raise \exam{domain_error(expected, culprit)}.  See domain_error/2.

    \cfunction{int}{PL_existence_error}{const char *type, term_t culprit}
Raise \exam{existence_error(type, culprit)}.  See type_error/2.

    \cfunction{int}{PL_permission_error}{const char *operation,
					 const char *type, term_t culprit}
Raise \exam{permission_error(operation, type, culprit)}. See
permission_error/3.
    \cfunction{int}{PL_resource_error}{const char *resource}
Raise \exam{resource_error(resource)}. See resource_error/1.
    \cfunction{int}{PL_syntax_error}{const char *message, IOSTREAM *in}
Raise \exam{syntax_error(message)}.  If \arg{arg} is not \const{NULL},
add information about the current position of the input stream.
\end{description}


\subsection{Serializing and deserializing Prolog terms}
\label{sec:foreign-serialize}

\begin{description}
    \cfunction{int}{PL_put_term_from_chars}{term_t t, int flags,
					    size_t len, const char *s}
Parse the text from the C-string \arg{s} holding \arg{len} bytes and
put the resulting term in \arg{t}.  \arg{len} can be \exam{(size_t)-1},
assuming a 0-terminated string.  The \arg{flags} argument controls the
encoding and is currently one of \const{REP_UTF8} (string is UTF8
encoded), \const{REP_MB} (string is encoded in the current locale)
or 0 (string is encoded in ISO latin 1).  The string may, but is
not required, to be closed by a full stop (.).

If parsing produces an exception the behaviour depends on the
\const{CVT_EXCEPTION} flag. If present, the exception is propagated into
the environment.  Otherwise the exceptuion is placed in \arg{t} and
the return value is \const{FALSE}.\footnote{The \const{CVT_EXCEPTION}
was added in version 8.3.12}.
\end{description}


\subsection{BLOBS: Using atoms to store arbitrary binary data}
\label{sec:blob}

\index{Java}\index{COM}
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
\cfuncref{compare}{} function.  Rank numbers are assigned when the
type is registered.


\subsubsection{Defining a BLOB type}
\label{sec:blobtype}

The type \ctype{PL_blob_t} represents a structure with the layout
displayed below. The structure contains additional fields at the
\ldots for internal bookkeeping as well as future extensions.

\begin{code}
typedef struct PL_blob_t
{ uintptr_t	magic;		/* PL_BLOB_MAGIC */
  uintptr_t	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);
  void		(*acquire)(atom_t a);
  ...
} PL_blob_t;
\end{code}

For each type, exactly one such structure should be allocated.  Its
first field must be initialised to \const{PL_BLOB_MAGIC}.  The
\arg{flags} is a bitwise \emph{or} of the following constants:

\begin{description}
    \constitem{PL_BLOB_TEXT}
If specified the blob is assumed to contain text and is considered
a normal Prolog atom.

    \constitem{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.

    \constitem{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 \const{PL_BLOB_UNIQUE}
is also specified, uniqueness is determined by comparing the pointer
rather than the data pointed at.
\end{description}

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

\begin{description}
    \cfunction{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.

    \cfunction{int}{release}{atom_t a}
The blob (atom) \arg{a} is about to be released.  This function
can retrieve the data of the blob using PL_blob_data().  If it
returns \const{FALSE} the atom garbage collector will \emph{not}
reclaim the atom.

    \cfunction{int}{compare}{atom_t a, atom_t b}
Compare the blobs \arg{a} and \arg{b}, both of which are of the
type associated to this blob type.  Return values are, as memcmp(),
$< 0$ if \arg{a} is less than \arg{b}, $= 0$ if both are equal, and
$> 0$ otherwise.

    \cfunction{int}{write}{IOSTREAM *s, atom_t a, int flags}
Write the content of the blob \arg{a} to the stream \arg{s}
respecting the \arg{flags}.  The \arg{flags} are a bitwise
\emph{or} of zero or more of the \const{PL_WRT_*} flags defined in
\file{SWI-Prolog.h}. This prototype is available if the
undocumented \file{SWI-Stream.h} is included \emph{before}
\file{SWI-Prolog.h}.

If this function is not provided, write/1 emits the content
of the blob for blobs of type \const{PL_BLOB_TEXT} or a
string of the format \verb$<#$\textit{hex data}\verb$>$
for binary blobs.
\end{description}

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.

\begin{description}
    \cfunction{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 \const{unregistered}, avoiding further
reference to the type structure, functions referred by it, as well as the
data. This function returns \const{TRUE} if no blobs of this type
existed and \const{FALSE} otherwise. PL_unregister_blob_type() is
intended for the uninstall() hook of foreign modules, avoiding further
references to the module.
\end{description}


\subsubsection{Accessing blobs}
\label{sec:blobaccess}

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

\begin{description}
    \cfunction{int}{PL_is_blob}{term_t t, PL_blob_t **type}
Succeeds if \arg{t} refers to a blob, in which case \arg{type} is
filled with the type of the blob.

    \cfunction{int}{PL_unify_blob}{term_t t, void *blob, size_t len,
				   PL_blob_t *type}
Unify \arg{t} to a new blob constructed from the given data and
associated to the given type.  See also PL_unify_atom_nchars().

    \cfunction{int}{PL_put_blob}{term_t t, void *blob, size_t len,
				 PL_blob_t *type}
Store the described blob in \arg{t}.  The return value indicates whether
a new blob was allocated (\const{FALSE}) or the blob is a reference to
an existing blob (\const{TRUE}).  Reporting new/existing can be used to
deal with external objects having their own reference counts.  If the
return is \const{TRUE} this reference count must be incremented, and it
must be decremented on blob destruction callback.  See also
PL_put_atom_nchars().

    \cfunction{int}{PL_get_blob}{term_t t, void **blob, size_t *len,
				 PL_blob_t **type}
If \arg{t} holds a blob or atom, get the data and type and return
\const{TRUE}.  Otherwise return \const{FALSE}.  Each result pointer
may be \const{NULL}, in which case the requested information is
ignored.

    \cfunction{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 \secref{blobtype}.
\end{description}


\subsection{Exchanging GMP numbers}
\label{sec:gmpforeign}

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 \verb$<gmp.h>$ must be included \emph{before}
\verb$<SWI-Prolog.h>$. Foreign code using GMP linked to SWI-Prolog asks
for some considerations.

\begin{itemize}
    \item 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
    \verb$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 \verb$PL_action(PL_GMP_SET_ALLOC_FUNCTIONS, FALSE)$
    \emph{before} initializing Prolog.

    \item 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.
\end{itemize}

Here is an example exploiting the function mpz_nextprime():

\begin{code}
#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);
}
\end{code}

\begin{description}
    \cfunction{int}{PL_get_mpz}{term_t t, mpz_t mpz}
If \arg{t} represents an integer, \arg{mpz} is filled with the value and
the function returns \const{TRUE}. Otherwise \arg{mpz} is untouched and
the function returns \const{FALSE}.  Note that \arg{mpz} must have been
initialised before calling this function and must be cleared using
mpz_clear() to reclaim any storage associated with it.

    \cfunction{int}{PL_get_mpq}{term_t t, mpq_t mpq}
If \arg{t} is an integer or rational number (term \functor{rdiv}{2}),
\arg{mpq} is filled with the \emph{normalised} rational number and the
function returns \const{TRUE}.  Otherwise \arg{mpq} is untouched and
the function returns \const{FALSE}.  Note that \arg{mpq} must have been
initialised before calling this function and must be cleared using
mpq_clear() to reclaim any storage associated with it.

    \cfunction{int}{PL_unify_mpz}{term_t t, mpz_t mpz}
Unify \arg{t} with the integer value represented by \arg{mpz} and return
\const{TRUE} on success.  The \arg{mpz} argument is not changed.

    \cfunction{int}{PL_unify_mpq}{term_t t, mpq_t mpq}
Unify \arg{t} with a rational number represented by \arg{mpq} and return
\const{TRUE} on success.  Note that \arg{t} is unified with an integer if
the denominator is 1.  The \arg{mpq} argument is not changed.
\end{description}


\subsection{Calling Prolog from C}
\label{sec: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 then 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.


\subsubsection{Predicate references}
\label{sec:foreign-predicate-handle}

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

\begin{description}
    \cfunction{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
\arg{m} is \const{NULL}, the current context module is used.

    \cfunction{predicate_t}{PL_predicate}{const char *name, int arity,
					  const char* module}
Same as PL_pred(), but provides a more convenient interface to
the C programmer.

    \cfunction{void}{PL_predicate_info}{predicate_t p, atom_t *n,
					size_t *a, module_t *m}
Return information on the predicate \arg{p}. The name is stored over
\arg{n}, the arity over \arg{a}, while \arg{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. Any of the arguments \arg{n}, \arg{a} and \arg{m} can be
\const{NULL}.
\end{description}


\subsubsection{Initiating a query from C}
\label{sec:foreign-create-query}

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 that it is allowed to make strictly nested
calls between C and Prolog (Prolog calls C, calls Prolog, calls C,
etc.), but it is \strong{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.


\begin{description}
\cfunction{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. \arg{ctx} is the {\em
context module} of the goal. When \const{NULL}, the context module of
the calling context will be used, or \const{user} if there is no calling
context (as may happen in embedded systems). Note that the context
module only matters for \jargon{meta-predicates}. See meta_predicate/1,
context_module/1 and module_transparent/1. The \arg{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 \arg{t0}
is the first of a vector of term references as returned by
PL_new_term_refs(n).

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

\begin{description}
    \definition{\const{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.%
	\footnote{Do not pass the integer 0 for normal operation, as
		  this is interpreted as \const{PL_Q_NODEBUG} for
		  backward compatibility reasons.}
    \definition{\const{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.
    \definition{\const{PL_Q_CATCH_EXCEPTION}}
If an exception is raised while executing the goal, do not report it, but
make it available for PL_exception().
    \definition{\const{PL_Q_PASS_EXCEPTION}}
As \const{PL_Q_CATCH_EXCEPTION}, but do not invalidate the exception-term
while calling PL_close_query().  This option is experimental.
    \definition{\const{PL_Q_ALLOW_YIELD}}
Support the \const{I_YIELD} instruction for engine-based coroutining.
See \nopredref{\$engine_yield}{2} in \file{boot/init.pl} for details.
    \definition{\const{PL_Q_EXT_STATUS}}
Make PL_next_solution() return extended status.  Instead of only
\const{TRUE} or \const{FALSE} extended status as illustrated in the
following table:

\begin{center}
\begin{tabular}{llp{4in}}
\bf Extended & \bf Normal & \\
\hline
PL_S_EXCEPTION	& FALSE & Exception available through PL_exception() \\
PL_S_FALSE	& FALSE & Query failed \\
PL_S_TRUE	& TRUE & Query succeeded with choicepoint \\
PL_S_LAST	& TRUE & Query succeeded without choicepoint \\
\end{tabular}
\end{center}
\end{description}


PL_open_query() can return the query identifier `0' if there is not enough
space on the environment stack. This function succeeds, even if the
referenced predicate is not defined. In this case, running the query
using PL_next_solution() will return an existence_error. See
PL_exception().

The example below opens a query to the predicate \verb$is_a/2$ to find the
ancestor of `me'. The reference to the predicate is valid for the
duration of the process and may be cached by the client.

\begin{code}
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);
  ...
}
\end{code}

    \cfunction{int}{PL_next_solution}{qid_t qid}
Generate the first (next) solution for the given query.  The return
value is \const{TRUE} if a solution was found, or \const{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.

    \cfunction{int}{PL_cut_query}{qid_t qid}
Discards the query, but does not delete any of the data created by the
query.  It just invalidates \arg{qid}, allowing for a new call to
PL_open_query() in this context.  PL_cut_query() may invoke cleanup
handlers (see setup_call_cleanup/3) and therefore may experience
exceptions.  If an exception occurs the return value is \const{FALSE}
and the exception is accessible through \exam{PL_exception(0)}.

    \cfunction{int}{PL_close_query}{qid_t qid}
As PL_cut_query(), but all data and bindings created by the query are
destroyed.

    \cfunction{qid_t}{PL_current_query}{void}
Returns the query id of of the current query or \const{0} if the
current thread is not executing any queries.

    \cfunction{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().
    \cfunction{int}{PL_call}{term_t t, module_t m}
Call term \arg{t} just like the Prolog predicate once/1. \arg{t} is called
in the module \arg{m}, or in the context module if \arg{m} == NULL.
Returns \const{TRUE} if the call succeeds, \const{FALSE} otherwise.
\Figref{calling} shows an example to obtain the number of
defined atoms. All checks are omitted to improve readability.
\end{description}

\subsection{Discarding Data}
\label{sec:foreign-discard-term-t}

The Prolog data created and term references needed to set up the call
and/or analyse the result can in most cases be discarded right after the
call. PL_close_query() allows for destroying the data, while leaving
the term references. The calls below may be used to destroy
term references and data. See \figref{calling} for an example.

\begin{description}
\cfunction{fid_t}{PL_open_foreign_frame}{}
Create 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.
\cfunction{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.
\cfunction{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.
\cfunction{void}{PL_rewind_foreign_frame}{fid_t id}
Undo all bindings and discard all term references created since the
frame was created, but do not pop the frame.  That is, the same frame
can be rewound multiple times, and must eventually be closed or
discarded.
\end{description}

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


\begin{figure}

\begin{code}
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;
}
\end{code}

     \caption{Calling Prolog}
     \label{fig:calling}
\end{figure}

\subsection{String buffering}
\label{sec:foreign-strings}

Many of the functions of the foreign language interface involve strings.
Some of these strings point into static memory like those associated
with atoms. These strings are valid as long as the atom is protected
against atom garbage collection, which generally implies the atom must
be locked using PL_register_atom() or be part of an accessible term.
Other strings are more volatile. Several functions provide a BUF_* flag
that can be set to either \const{BUF_STACK} (default) or
\const{BUF_MALLOC}. Strings returned by a function accepting
\const{BUF_MALLOC} \textbf{must} be freed using PL_free(). Strings
returned using \const{BUF_STACK} are pushed on a stack that is cleared
when a foreign predicate returns control back to Prolog. More fine
grained control may be needed if functions that return strings are
called outside the context of a foreign predicate or a foreign predicate
creates many strings during its execution.  Temporary strings are scoped
using these macros:

\begin{description}
    \cmacro{void}{PL_STRINGS_MARK}{}
    \nodescription
    \cmacro{void}{PL_STRINGS_RELEASE}{}
These macros must be paired and create a C \jargon{block} (\{...\}). Any
string created using \const{BUF_STACK} after PL_STRINGS_MARK() is
released by the corresponding PL_STRINGS_RELEASE().  These macros
should be used like below

\begin{code}
  ...
  PL_STRINGS_MARK();
  <operations involving strings>
  PL_STRINGS_RELEASE();
  ...
\end{code}
\end{description}

The Prolog flag \prologflag{string_stack_tripwire} may be used to set a
\jargon{tripwire} to help finding places where scoping strings may help
reducing resources.

\subsection{Foreign Code and Modules}
\label{sec:foreign-modules}

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

\begin{description}
    \cfunction{module_t}{PL_context}{}
Return the module identifier of the context module of the currently
active foreign predicate.

    \cfunction{int}{PL_strip_module}{term_t +raw, module_t *m, term_t -plain}
Utility function. If \arg{raw} is a term, possibly holding the module
construct \mbox{<module>{\tt :}<rest>}, this function will make
\arg{plain} a reference to <rest> and fill \arg{module *} with <module>.
For further nested module constructs the innermost module is returned
via \arg{module *}. If \arg{raw} is not a module construct, \arg{raw}
will simply be put in \arg{plain}. The value pointed to by \arg{m} must
be initialized before calling PL_strip_module(), either to the default
module or to \const{NULL}. A \const{NULL} value is replaced by the
current context module if \arg{raw} carries no module. The following
example shows how to obtain the plain term and module if the default
module is the user module:

\begin{code}
{ module m = PL_new_module(PL_new_atom("user"));
  term_t plain = PL_new_term_ref();

  PL_strip_module(term, &m, plain);
  ...
}
\end{code}


\cfunction{atom_t}{PL_module_name}{module_t module}
Return the name of \arg{module} as an atom.
\cfunction{module_t}{PL_new_module}{atom_t name}
Find an existing module or create a new module with the name \arg{name}.
\end{description}


\subsection{Prolog exceptions in foreign code}
\label{sec:foreign-exceptions}

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 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 \const{FALSE}. If a foreign predicate returns \const{FALSE}, while
an 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
\strong{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.

\begin{code}
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);			/* do not destroy data */
    PL_close_foreign_frame(fid);	/* same */
  }

  return rval;
}
\end{code}


\begin{description}
    \cfunction{int}{PL_raise_exception}{term_t exception}
Generate an exception (as throw/1) and return \const{FALSE}.  Below is
an example returning an exception from a foreign predicate:

\begin{code}
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);
  }
}
\end{code}
    \cfunction{int}{PL_throw}{term_t exception}
Similar to PL_raise_exception(), but returns using the C longjmp()
function to the innermost PL_next_solution().

    \cfunction{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. If there is an exception,
PL_exception() allocates a term-handle using PL_new_term_ref() that is
used to return the exception term.

Additionally, \verb$PL_exception(0)$ returns the pending exception in
the current query or 0 if no exception is pending. This can be used to
check the error status after a failing call to, e.g., one of the
unification functions.

    \cfunction{void}{PL_clear_exception}{void}
Tells Prolog that the encountered exception must be ignored. This
function must be called if control remains in C after a previous API
call fails with an exception.\footnote{This feature is non-portable.
Other Prolog systems (e.g., YAP) have no facilities to ignore raised
exceptions, and the design of YAP's exception handling does not support
such a facility.}
\end{description}


\subsection{Catching Signals (Software Interrupts)}	\label{sec:csignal}

SWI-Prolog offers both a C and Prolog interface to deal with software
interrupts (signals). The Prolog mapping is defined in
\secref{signal}. 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.

Any handler that wishes to call one of the Prolog interface functions
should call PL_sigaction() to install the handler.  PL_signal() provides
a deprecated interface that is notably not capable of properly restoring
the old signal status if the signal was previously handled by Prolog.

\begin{description}
    \cfunction{int}{PL_sigaction}{int sig, pl_sigaction_t *act,
				  pl_sigaction_t *oldact}
Install or query the status for signal \arg{sig}.  The signal is
an integer between 1 and 64, where the where the signals up to 32
are mapped to OS signals and signals above that are handled by
Prolog's synchronous signal handling.  The \ctype{pl_sigaction_t}
is a struct with the following definition:

\begin{code}
typedef struct pl_sigaction
{ void        (*sa_cfunction)(int);	/* traditional C function */
  predicate_t sa_predicate;		/* call a predicate */
  int	      sa_flags;			/* additional flags */
} pl_sigaction_t;
\end{code}

The \const{sa_flags} is a bitwise or of \const{PLSIG_THROW},
\const{PLSIG_SYNC} and \const{PLSIG_NOFRAME}. Signal handling is enabled
if \const{PLSIG_THROW} is provided, \const{sa_cfunction} or
\const{sa_predicate} is provided. \const{sa_predicate} is a predicate
handle for a predicate with arity~1. If no action is provided the signal
handling for this signal is restored to the default before
PL_initialise() was called.

Finally, 0 (zero) may be passed for \arg{sig}.  In that case the system
allocates a free signal in the \textit{Prolog range} (32\ldots{}64).
Such signal handler are activated using PL_thread_raise().

    \cfunction{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 \jargon{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 \emph{or}-ing \arg{sig} with the constant
\const{PL_SIGSYNC}.%
    \footnote{A 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();

    \cfunction{int}{PL_raise}{int sig}
Register \arg{sig} for \emph{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.

    \cfunction{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 \const{FALSE} as
soon as possible.

    \cfunction{int}{PL_get_signum_ex}{term_t t, int *sig}
Extract a signal specification from a Prolog term and store as an integer
signal number in \arg{sig}.  The specification is an integer, a lowercase
signal name without \const{SIG} or the full signal name.  These refer
to the same: \verb$9$, \verb$kill$ and \verb$SIGKILL$. Leaves a typed,
domain or instantiation error if the conversion fails.
\end{description}


\subsection{Miscellaneous}
\label{sec:foreign-misc}

\subsubsection{Term Comparison}
\label{sec:foreign-compare}

\begin{description}
\cfunction{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.
\cfunction{int}{PL_same_compound}{term_t t1, term_t t2}
    Yields \const{TRUE} if \arg{t1} and \arg{t2} refer to physically
    the same compound term and \const{FALSE} otherwise.
\end{description}

\subsubsection{Recorded database}
\label{sec:foreign-recorded}

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.

\begin{description}
\cfunction{record_t}{PL_record}{term_t +t}
    Record the term \arg{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.

\cfunction{record_t}{PL_duplicate_record}{record_t record}
    Return a duplicate of \arg{record}.  As records are read-only
    objects this function merely increments the records reference
    count.

\cfunction{int}{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. Returns \const{TRUE} on success, and \const{FALSE} if
    there is not enough space on the stack to accommodate the term.
    See also PL_record() and PL_erase().

\cfunction{void}{PL_erase}{record_t record}
    Remove the recorded term from the Prolog database, reclaiming all
    associated memory resources.
\end{description}

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 and compact in an external database.	Here are
the main features:

\begin{itemlist}
    \item [Independent of session]
Records can be communicated to another Prolog session and made visible
using PL_recorded_external().
    \item [Binary]
The representation is binary for maximum performance.  The returned data
may contain zero bytes.
    \item [Byte-order independent]
The representation can be transferred between machines with different
byte order.
    \item [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.
    \item [Compact]
It is assumed that a smaller memory footprint will eventually outperform
slightly faster representations.
    \item [Stable]
The format is designed for future enhancements without breaking
compatibility with older records.
\end{itemlist}

\begin{description}
\cfunction{char *}{PL_record_external}{term_t +t, size_t *len}
    Record the term \arg{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.
\cfunction{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().
\cfunction{int}{PL_erase_external}{char *record}
    Remove the recorded term from the Prolog database, reclaiming all
    associated memory resources.
\end{description}


\subsubsection{Database}
\label{sec:foreign-db}

\begin{description}
    \cfunction{int}{PL_assert}{term_t t, module_t m, int flags}
Provides direct access to asserta/1 and assertz/1 by asserting \arg{t}
into the database in the module \arg{m}.  Defined flags are:

    \begin{description}
	\termitem{PL_ASSERTZ}{}
Add the new clause as last. Calls assertz/1. This macros is defined as 0
and thus the default.
	\termitem{PL_ASSERTA}{}
Add the new clause as first.  Calls asserta/1.
	\termitem{PL_CREATE_THREAD_LOCAL}{}
If the predicate is not defined, create it as thread-local.  See
thread_local/1.
	\termitem{PL_CREATE_INCREMENTAL}{}
If the predicate is not defined, create it as \jargon{incremental} see
table/1 and \secref{tabling-incremental}.
    \end{description}

On success this function returns \const{TRUE}. On failure \const{FALSE}
is returned and an exception is left in the environment that describes
the reason of failure.  See PL_exception().

This predicate bypasses creating a Prolog callback environment and is
faster than setting up a call to assertz/1. It may be used together with
PL_chars_to_term(), but the typical use case will create a number of
clauses for the same predicate. The fastest way to achieve this is by
creating a term that represents the invariable structure of the desired
clauses using variables for the variable sub terms. Now we can loop over
the data, binding the variables, asserting the term and undoing the
bindings. Below is an example loading words from a file that contains a
word per line.

\begin{code}
#include <SWI-Prolog.h>
#include <stdio.h>
#include <string.h>

#define MAXWLEN 256

static foreign_t
load_words(term_t name)
{ char *fn;

  if ( PL_get_file_name(name, &fn, PL_FILE_READ) )
  { FILE *fd = fopen(fn, "r");
    char word[MAXWLEN];
    module_t m = PL_new_module(PL_new_atom("words"));
    term_t cl = PL_new_term_ref();
    term_t w  = PL_new_term_ref();
    fid_t fid;

    if ( !PL_unify_term(cl, PL_FUNCTOR_CHARS, "word", 1, PL_TERM, w) )
      return FALSE;

    if ( (fid = PL_open_foreign_frame()) )
    { while(fgets(word, sizeof(word), fd))
      { size_t len;

	if ( (len=strlen(word)) )
	{ word[len-1] = '\0';
	  if ( !PL_unify_chars(w, PL_ATOM|REP_MB, (size_t)-1, word) ||
	       !PL_assert(cl, m, 0) )
	    return FALSE;
	  PL_rewind_foreign_frame(fid);
	}
      }

      PL_close_foreign_frame(fid);
    }

    fclose(fd);
    return TRUE;
  }

  return FALSE;
}

install_t
install(void)
{ PL_register_foreign("load_words", 1, load_words, 0);
}
\end{code}
\end{description}


\subsubsection{Getting file names}		\label{sec:cfilenames}

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.

\begin{description}
    \cfunction{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
buffer stack described with the PL_get_chars() option \const{BUF_STACK}.
Conversion from the internal UNICODE encoding is done using standard C
library functions. \arg{flags} is a bit-mask controlling the conversion
process. Options are:

\begin{description}
    \definition{\const{PL_FILE_ABSOLUTE}}
Return an absolute path to the requested file.
    \definition{\const{PL_FILE_OSPATH}}
Return the name using the hosting OS conventions.  On MS-Windows,
\chr{\} is used to separate directories rather than the canonical
\chr{/}.
    \definition{\const{PL_FILE_SEARCH}}
Invoke absolute_file_name/3.  This implies rules from file_search_path/2
are used.
    \definition{\const{PL_FILE_EXIST}}
Demand the path to refer to an existing entity.
    \definition{\const{PL_FILE_READ}}
Demand read-access on the result.
    \definition{\const{PL_FILE_WRITE}}
Demand write-access on the result.
    \definition{\const{PL_FILE_EXECUTE}}
Demand execute-access on the result.
    \definition{\const{PL_FILE_NOERRORS}}
Do not raise any exceptions.
\end{description}

\cfunction{int}{PL_get_file_nameW}{term_t spec, wchar_t **name, int flags}
Same as PL_get_file_name(), but returns the filename as a wide-character
string. This is intended for Windows to access the Unicode version of
the Win32 API. Note that the flag \const{PL_FILE_OSPATH} must be
provided to fetch a filename in OS native (e.g., \verb$C:\x\y$)
notation.
\end{description}


\subsubsection{Dealing with Prolog flags from C}
\label{sec:cprologflags}

Foreign code can set or create Prolog flags using PL_set_prolog_flag().
See set_prolog_flag/2 and create_prolog_flag/3. To retrieve the value
of a flag you can use PL_current_prolog_flag().

\begin{description}
    \cfunction{int}{PL_set_prolog_flag}{const char *name, int type, ...}
Set/create a Prolog flag from C.  \arg{name} is the name of the affected
flag. \arg{type} is one of the values below, which also
dictates the type of the final argument. The function returns
\const{TRUE} on success and \const{FALSE} on failure.  This function
can be called \emph{before} PL_initialise(), making the flag available
to the Prolog startup code.

\begin{description}
    \definition{\const{PL_BOOL}}
Create a boolean (\const{true} or \const{false}) flag. The argument must
be an \ctype{int}.
    \definition{\const{PL_ATOM}}
Create a flag with an atom as value. The argument must be of type
\ctype{const char *}.
    \definition{\const{PL_INTEGER}}
Create a flag with an integer as value. The argument must be of type
\ctype{intptr_t *}.
\end{description}
\end{description}


\begin{description}
    \cfunction{int}{PL_current_prolog_flag}{atom_t name, int type, void *value}
Retrieve the value of a Prolog flag from C.  \arg{name} is the name of the
flag as an \const{atom_t} (see current_prolog_flag/2).
\arg{type} specifies the kind of value to be retrieved, it is one
of the values below.  \arg{value} is a pointer to a location where
to store the value. The user is responsible for making sure this memory
location is of the appropriate size/type (see the returned types below
to determine the size/type).
The function returns \const{TRUE} on success
and \const{FALSE} on failure.

\begin{description}
    \definition{\const{PL_ATOM}}
Retrieve a flag whose value is an \const{atom}. The returned value is an atom handle of type \ctype{atom_t}.
    \definition{\const{PL_INTEGER}}
Retrieve a flag whose value is an \const{integer}. The returned value is an  integer of type \ctype{int64_t}.
    \definition{\const{PL_FLOAT}}
Retrieve a flag whose value is a \const{float}. The returned value is a floating point number of type \ctype{double}.
    \definition{\const{PL_TERM}}
Retrieve a flag whose value is a \const{term}. The returned value is a term handle of type \ctype{term_t}.
\end{description}
\end{description}

\subsection{Errors and warnings}
\label{sec:foreign-print-warning}

PL_warning() prints a standard Prolog warning message to the standard
error (\const{user_error}) stream. Please note that new code should
consider using PL_raise_exception() to raise a Prolog exception. See
also \secref{exception}.

\begin{description}
\cfunction{int}{PL_warning}{format, a1, \ldots}
Print an error message starting with `{\tt [WARNING: }', followed
by the output from \arg{format}, followed by a `\chr{]}' and a newline.
Then start the tracer. \arg{format} and the arguments are the same as
for \manref{printf}{2}. Always returns \const{FALSE}.
\end{description}

\subsection{Environment Control from Foreign Code}
\label{sec:foreign-control-prolog}

\begin{description}
\cfunction{int}{PL_action}{int, ...}
Perform some action on the Prolog system. \arg{int} describes the
action. Remaining arguments depend on the requested action. The actions
are listed below:

\begin{description}
    \termitem{PL_ACTION_TRACE}{}
Start Prolog tracer (trace/0).  Requires no arguments.

    \termitem{PL_ACTION_DEBUG}{}
Switch on Prolog debug mode (debug/0).  Requires no arguments.

    \termitem{PL_ACTION_BACKTRACE}{}
Print backtrace on current output stream.  The argument (an \ctype{int})
is the number of frames printed.

    \termitem{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 \ctype{int}) is the exit code. See halt/1.

    \termitem{PL_ACTION_ABORT}{}
Generate a Prolog abort (abort/0). This call does not return. Requires
no arguments.

    \termitem{PL_ACTION_BREAK}{}
Create a standard Prolog break environment (break/0). Returns after the
user types the end-of-file character. Requires no arguments.

    \termitem{PL_ACTION_GUIAPP}{}
Windows: Used to indicate to 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 otherwise simply
prints the error and exits.

    \termitem{PL_ACTION_TRADITIONAL}{}
Same effect as using \cmdlineoption{--traditional}.  Must be called
\emph{before} PL_initialise().

    \termitem{PL_ACTION_WRITE}{}
Write the argument, a \ctype{char *} to the current output stream.

    \termitem{PL_ACTION_FLUSH}{}
Flush the current output stream.  Requires no arguments.

    \termitem{PL_ACTION_ATTACH_CONSOLE}{}
Attach a console to a thread if it does not have one. See
attach_console/0.

    \termitem{PL_GMP_SET_ALLOC_FUNCTIONS}{}
Takes an integer argument. If \const{TRUE}, the GMP allocations are
immediately bound to the Prolog functions. If \const{FALSE}, SWI-Prolog
will never rebind the GMP allocation functions. See
mp_set_memory_functions() in the GMP documentation. The action returns
\const{FALSE} if there is no GMP support or GMP is already initialised.
\end{description}

\cfunction{unsigned int}{PL_version}{int key}
Query version information.  This function may be called before
PL_initialise().  If the key is unknown the function returns 0.
See \secref{abi-versions} for a more in-depth discussion on
binary compatibility.  Defined keys are:

    \begin{description}
	\termitem{PL_VERSION_SYSTEM}{}
SWI-Prolog version as $10,000 \times major + 100 \times minor + patch$.
	\termitem{PL_VERSION_FLI}{}
Incremented if the foreign interface defined in this chapter changes in
a way that breaks backward compatibility.
	\termitem{PL_VERSION_REC}{}
Incremented if the binary representation of terms as used by
PL_record_external() and fast_write/2 changes.
	\termitem{PL_VERSION_QLF}{}
Incremented if the QLF file format changes.
	\termitem{PL_VERSION_QLF_LOAD}{}
Represents the oldest loadable QLF file format version.
	\termitem{PL_VERSION_VM}{}
A hash that represents the VM instructions and their arguments.
	\termitem{PL_VERSION_BUILT_IN}{}
A hash that represents the names, arities and properties of all
built-in predicates defined in C.  If this function is called
before PL_initialise() it returns 0.
    \end{description}
\end{description}

\subsection{Querying Prolog}
\label{sec:foreign-query}

\begin{description}
\cfunction{long}{PL_query}{int}
Obtain status information on the Prolog system. The actual argument
type depends on the information required. \arg{int} describes what
information is wanted.%
	\footnote{Returning pointers and integers as a long is bad
		  style.  The signature of this function should be
		  changed.}
The  options are given in \tabref{query}.


\begin{table}
\begin{quote}\begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|}
\hline
\const{PL_QUERY_ARGC}       & Return an integer holding the number of
                              arguments given to Prolog from Unix. \\
\const{PL_QUERY_ARGV}       & Return a \ctype{char **} holding the argument vector
                              given to Prolog from Unix. \\
\const{PL_QUERY_SYMBOLFILE} & Return a \ctype{char *} holding the current symbol
                              file of the running process. \\
\const{PL_MAX_INTEGER}      & Return a long, representing the maximal integer
                              value represented by a Prolog integer. \\
\const{PL_MIN_INTEGER}      & Return a long, representing the minimal integer
                              value. \\
\const{PL_QUERY_VERSION}    & Return a long, representing the version as
                              $10,000 \times M + 100 \times m + p$, where
                              $M$ is the major, $m$ the minor version number
                              and $p$ the patch level.  For example,
                              \exam{20717} means \exam{2.7.17}. \\
\const{PL_QUERY_ENCODING}    & Return the default stream encoding of
			       Prolog (of type \ctype{IOENC}). \\
\const{PL_QUERY_USER_CPU}    & Get amount of user CPU time of the
			       process in milliseconds. \\
\hline
\end{tabular}\end{quote}

    \caption{PL_query() options}
    \label{tab:query}
\end{table}
\end{description}


\subsection{Registering Foreign Predicates}
\label{sec:foreign-register-predicate}

\begin{description}
\cfunction{int}{PL_register_foreign_in_module}{char *mod,
					       char *name, int arity,
					       foreign_t (*f)(),
					       int flags, ...}
Register the C function \arg{f} to implement a Prolog predicate. After
this call returns successfully a predicate with name \arg{name} (a
\ctype{char *}) and arity \arg{arity} (a C \ctype{int}) is created in
module \arg{mod}. If \arg{mod} is \const{NULL}, the predicate is created
in the module of the calling context, or if no context is present in the
module \const{user}.

When called in Prolog, Prolog will call \arg{function}. \arg{flags}
form a bitwise \emph{or}'ed list of options for the installation. These are:

\begin{tabular}{|p{\tableft}|p{\linewidth-\tableft-2cm}|}
\hline
\const{PL_FA_META}	       & Provide meta-predicate info (see below) \\
\const{PL_FA_TRANSPARENT}      & Predicate is module transparent (deprecated) \\
\const{PL_FA_NONDETERMINISTIC} & Predicate is non-deterministic.
                                 See also PL_retry(). \\
\const{PL_FA_NOTRACE}          & Predicate cannot be seen in the tracer \\
\const{PL_FA_VARARGS}	       & Use alternative calling convention. \\
\hline
\end{tabular}

If \const{PL_FA_META} is provided, PL_register_foreign_in_module() takes
one extra argument. This argument is of type \ctype{const char*}. This
string must be exactly as long as the number of arguments of the
predicate and filled with characters from the set \verb$0-9:^-+?$. See
meta_predicate/1 for details. \const{PL_FA_TRANSPARENT} is implied if at
least one meta-argument is provided (\verb$0-9:^$). Note that
meta-arguments are \emph{not always} passed as <module>:<term>. Always
use PL_strip_module() to extract the module and plain term from a
meta-argument.\footnote{It is encouraged to pass an additional \const{NULL}
pointer for non-meta-predicates.}

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 \const{PL_FA_VARARGS}) \arg{function} is
passed the same number of \ctype{term_t} arguments as the arity of the predicate
and, if the predicate is non-deterministic, an extra argument of type
\ctype{control_t} (see \secref{foreignnondet}). If \const{PL_FA_VARARGS}
is provided, \arg{function} is called with three arguments. The first
argument is a \ctype{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 \ctype{void*}.  Here is an example:

\begin{code}
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);
}
\end{code}

\cfunction{int}{PL_register_foreign}{const char *name, int arity,
				     foreign_t (*function)(),
				     int flags, ...}
Same as PL_register_foreign_in_module(), passing \const{NULL} for the
\arg{module}.

    \cfunction{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
\ctype{PL_extension} in the given \arg{module}. If \arg{module} is
\const{NULL}, the predicate is created in the module of the calling
context, or if no context is present in the module \const{user}.
The \ctype{PL_extension} type is defined as

\begin{code}
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;
\end{code}

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

\begin{code}
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);

  ...
}
\end{code}

    \cfunction{void}{PL_register_extensions}{ PL_extension *e}
Same as PL_register_extensions_in_module() using \const{NULL} for
the \arg{module} argument.
\end{description}


\subsection{Foreign Code Hooks}
\label{sec:foreign-hooks}

For various specific applications some hooks are provided.

\begin{description}
\cfunction{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:
\const{PL_DISPATCH_INPUT} indicates Prolog input is available on file
descriptor 0 or \const{PL_DISPATCH_TIMEOUT} to indicate a timeout. The old
hook is returned. The type \ctype{PL_dispatch_hook_t} is defined as:

\begin{code}
typedef int  (*PL_dispatch_hook_t)(void);
\end{code}
    \cfunction{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
    \ctype{PL_abort_hook_t} is defined as:
\begin{code}
typedef void (*PL_abort_hook_t)(void);
\end{code}

    \cfunction{int}{PL_abort_unhook}{PL_abort_hook_t}
Remove a hook installed with PL_abort_hook(). Returns \const{FALSE} if no
such hook is found, \const{TRUE} otherwise.

    \cfunction{void}{PL_on_halt}{int (*f)(int, void *), void *closure}
Register the function \arg{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) and the \arg{closure} argument passed to
the PL_on_halt() call.  Handlers \emph{must} return 0.  Other return
values are reserved for future use. See also at_halt/1.\bug{Although
both PL_on_halt() and at_halt/1 are called in FIFO order, \emph{all}
at_halt/1 handlers are called before \emph{all} PL_on_halt() handlers.}
These handlers are called \emph{before} system cleanup and can therefore
access all normal Prolog resources.  See also PL_exit_hook().

    \cfunction{void}{PL_exit_hook}{int (*f)(int, void *), void *closure}
Similar to PL_on_halt(), but the hooks are executed by PL_halt() instead
of PL_cleanup() just before calling exit().

    \cfunction{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, \const{NULL}
is returned. The argument of the called hook is the atom that is to be
garbage collected.  The return value is an \ctype{int}.  If the return
value is zero, the atom is {\bf 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.

\begin{code}
#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);
}
\end{code}
\end{description}


\subsection{Storing foreign data}		\label{sec:foreigndata}

When combining foreign code with Prolog, it can be necessary to make
data represented in the foreign language available to Prolog. For
example, to pass it to another foreign function. At the end of this
section, there is a partial implementation of using foreign functions to
manage bit-vectors. Another example is the SGML/XML library that manages
a `parser' object, an object that represents the current state of the
parser and that can be directed to perform actions such as parsing a
document or make queries about the document content.

This section provides some hints for handling foreign data in Prolog.
There are four options for storing such data:

\begin{itemlist}
    \item[Natural Prolog data]
Uses the representation one would choose if no foreign interface was
required. For example, a bitvector representing a list of small integers can be
represented as a Prolog list of integers.

    \item[Opaque packed data on the stacks]
It is possible to represent the raw binary representation of the foreign
object as a Prolog string (see \secref{strings}). Strings may be created
from foreign data using PL_put_string_nchars() and retrieved using
PL_get_string_chars(). It is good practice to wrap the string in a
compound term with arity 1, so Prolog can identify the type. The hook
portray/1 rules may be used to streamline printing such terms during
development.

    \item[Opaque packed data in a blob]
Similar to the above solution, binary data can be stored in an atom. The
blob interface (\secref{blob}) provides additional facilities to assign
a type and hook-functions that act on creation and destruction of the
underlying atom.

    \item[Natural foreign data, passed as a pointer]
An alternative is to pass a pointer to the foreign data. Again, the
pointer is often wrapped in a compound term.
\end{itemlist}

\noindent
The choice may be guided using the following distinctions

\begin{itemlist}
    \item[Is the data opaque to Prolog]
With `opaque' data, we refer to data handled in foreign functions,
passed around in Prolog, but where Prolog never examines the contents of
the data itself. If the data is opaque to Prolog, the selection will be
driven solely by simplicity of the interface and performance.

    \item[What is the lifetime of the data]
With `lifetime' we refer to how it is decided that the object is (or can
be) destroyed. We can distinguish three cases:

    \begin{enumerate}
	\item
The object must be destroyed on backtracking and normal Prolog garbage
collection (i.e., it acts as a normal Prolog term). In this case,
representing the object as a Prolog string (second option above) is the
only feasible solution.

        \item
The data must survive Prolog backtracking. This leaves two options. One
is to represent the object using a pointer and use explicit creation and
destruction, making the programmer responsible. The alternative is to
use the blob-interface, leaving destruction to the (atom) garbage
collector.

	\item
The data lives as during the lifetime of a foreign function that
implements a 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 \secref{foreignnondet}.
    \end{enumerate}
\end{itemlist}


\subsubsection{Examples for storing foreign data}
\label{sec:foreign-store-data}

In this section, we 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. Then, we
discuss the outline of the DDE interface.

\paragraph{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 \emph{and}'ing and
\emph{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 \functor{bitvector}{1},
the 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.

\begin{code}
#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);
}
\end{code}

\paragraph{The DDE interface} (see \secref{DDE}) 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 \jargon{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 use 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, nor to verify that it is pointing to a structure of the desired
type.  The pointer may be wrapped into a compound term with arity
1 (i.e., \exam{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.


\subsection{Embedding SWI-Prolog in other applications}	\label{sec:embedded}

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 with 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() {\bf 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 \argoption{-t}{toplevel} flag that is
interpreted by PL_toplevel().

\begin{code}
int
main(int argc, char **argv)
{ if ( !PL_initialise(argc, argv) )
    PL_halt(1);

  PL_halt(PL_toplevel() ? 0 : 1);
}
\end{code}

\begin{description}
\cfunction{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 initialization/1 hooks and finally runs the initialization
goals registered using \argoption{-g}{goal}.

Special consideration is required for \verb$argv[0]$. On {\bf 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 {\bf Windows} version uses this to find
a \jargon{module} of the running executable.  If the specified module
cannot be found, it tries the module \const{libswipl.dll}, containing
the Prolog runtime kernel. In all these cases, the resulting file is
used for two purposes:

\begin{itemize}
    \item 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 \file{boot.prc} file from the SWI-Prolog home
	  directory.  See also qsave_program/[1,2] and \secref{plld}.
    \item Find the Prolog home directory.  This process is described
          in detail in \secref{findhome}.
\end{itemize}

PL_initialise() returns 1 if all initialisation succeeded and 0
otherwise.%
    \bug{Various fatal errors may cause PL_initialise() to call
	 PL_halt(1), preventing it from returning at all.}

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

\begin{code}
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);
  ...
}
\end{code}

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 \file{bin} directory
to your \env{PATH} and either pass a module holding a saved state, or
\verb$"libswipl.dll"$ as \verb$argv[0]$. If the Prolog state is attached
to a DLL (see the \cmdlineoption{-dll} option of \program{swipl-ld}),
pass the name of this DLL.

    \cfunction{int}{PL_winitialise}{int argc, wchar_t **argv}
Wide character version of PL_initialise(). Can be used in Windows
combined with the wmain() entry point.

    \cfunction{int}{PL_is_initialised}{int *argc, char ***argv}
Test whether the Prolog engine is already initialised. Returns
\const{FALSE} if Prolog is not initialised and \const{TRUE} otherwise.
If the engine is initialised and \arg{argc} is not \const{NULL}, the
argument count used with PL_initialise() is stored in \arg{argc}.  Same
for the argument vector \arg{argv}.

    \cfunction{int}{PL_set_resource_db_mem}{const unsigned char *data,
					    size_t size}
This function must be called at most once and \emph{before} calling
PL_initialise(). The memory area designated by \arg{data} and \arg{size}
must contain the resource data and be in the format as produced by
qsave_program/2. The memory area is accessed by PL_initialise() as well
as calls to open_resource/3.\footnote{This implies that the data must
remain accessible during the lifetime of the process if open_resource/3
is used.  Future versions may provide a function to detach the resource
database and cause open_resource/3 to raise an exception.}

For example, we can include the bootstrap data into an embedded
executable using the steps below. The advantage of this approach is that
it is fully supported by any OS and you obtain a single file executable.

\begin{enumerate}
    \item Create a saved state using qsave_program/2 or
\begin{code}
% swipl -o state -c file.pl ...
\end{code}
    \item Create a C source file from the state using e.g., the
    Unix utility \program{xxd}(1):
\begin{code}
% xxd -i state > state.h
\end{code}
    \item Embed Prolog as in the example below.  Instead of calling
    the toplevel you probably want to call your application code.
\begin{code}
#include <SWI-Prolog.h>
#include "state.h"

int
main(int argc, char **argv)
{ if ( !PL_set_resource_db_mem(state, state_len) ||
       !PL_initialise(argc, argv) )
    PL_halt(1);

  return PL_toplevel();
}
\end{code}
\end{enumerate}

Alternative to \program{xxd}, it is possible to use inline assembler,
e.g. the \program{gcc} \const{incbin} instruction. Code for
\program{gcc} was provided by Roberto Bagnara on the SWI-Prolog
mailinglist.  Given the state in a file \file{state}, create the
following assembler program:

\begin{code}
        .globl _state
        .globl _state_end
_state:
        .incbin "state"
_state_end:
\end{code}

Now include this as follows:

\begin{code}
#include <SWI-Prolog.h>

#if __linux
#define STATE _state
#define STATE_END _state_end
#else
#define STATE state
#define STATE_END state_end
#endif

extern unsigned char STATE[];
extern unsigned char STATE_END[];

int
main(int argc, char **argv)
{ if ( !PL_set_resource_db_mem(STATE, STATE_END - STATE) ||
       !PL_initialise(argc, argv) )
    PL_halt(1);
  return PL_toplevel();
}
\end{code}

As Jose Morales pointed at
\url{https://github.com/graphitemaster/incbin}, which contains a
portability layer on top of the above idea.

    \cfunction{int}{PL_toplevel}{}
Runs the goal of the \argoption{-t}{toplevel} switch (default prolog/0) and
returns 1 if successful, 0 otherwise.

    \cfunction{int}{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
if \arg{status} equals `0' and restores all signal handlers. The
\arg{status} argument is passed to the various termination hooks and
indicates the \jargon{exit-status}.

The function returns \const{TRUE} if successful and \const{FALSE}
otherwise. Currently, \const{FALSE} is returned when an attempt is made
to call PL_cleanup() recursively or if one of the exit handlers
cancels the termination using cancel_halt/1.  Exit handlers may only
cancel termination if \arg{status} is 0.

In theory, this function allows deleting and restarting the Prolog
system in the same process. In practice, SWI-Prolog's cleanup process is
far from complete, and trying to revive the system using PL_initialise()
will leak memory in the best case. It can also crash the application.

In this state, there is little practical use for this function. If you
want to use Prolog temporarily, consider running it in a separate process.
If you want to be able to reset Prolog, your options are (again) a
separate process, modules or threads.

    \cfunction{void}{PL_cleanup_fork}{}
Stop intervaltimer that may be running on behalf of profile/1.  The call
is intended to be used in combination with fork():

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

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

    \cfunction{int}{PL_halt}{int status}
Clean up the Prolog environment using PL_cleanup() and if successful
call exit() with the status argument.  Returns \const{FALSE} if exit
was cancelled by PL_cleanup().
\end{description}


\subsubsection{Threading, Signals and embedded Prolog}
\label{sec:sigembedded}

This section applies to Unix-based environments that have signals or
multithreading.  The Windows version is compiled for multithreading,
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
VMs, however, are by nature multithreaded and appear to do
signal handling (software interrupts).

On Unix systems, SWI-Prolog installs handlers for the following
signals:

\begin{description}
    \item[SIGUSR2] has an empty signal handler.   This signal is
    sent to a thread after sending a thread-signal (see
    thread_signal/2).  It causes blocking system calls to return
    with \const{EINTR}, which gives them the opportunity to react
    to thread-signals.

    In some cases the embedded system and SWI-Prolog may both use
    \const{SIGUSR2} without conflict. If the embedded system redefines
    \const{SIGUSR2} with a handler that runs quickly and no harm is
    done in the embedded system due to spurious wakeup when initiated
    from Prolog, there is no problem.  If SWI-Prolog is initialised
    \emph{after} the embedded system it will call the handler set by
    the embedded system and the same conditions as above apply.
    SWI-Prolog's handler is a simple function only chaining a possibly
    previously registered handler.  SWI-Prolog can handle spurious
    \const{SIGUSR2} signals.

    \item[SIGINT] is used by the top level to activate the tracer
    (typically bound to control-C).  The first control-C posts a
    request for	starting the tracer in a safe, synchronous fashion.
    If control-C is hit again before the safe route is executed,
    it prompts the user whether or not a forced interrupt is
    desired.

    \item[SIGTERM, SIGABRT and SIGQUIT] are caught to cleanup before
    killing the process again using the same signal.

    \item[SIGSEGV, SIGILL, SIGBUS, SIGFPE and SIGSYS] are caught by
    to print a backtrace before killing the process again using
    the same signal.

    \item[SIGHUP] is caught and causes the process to exit with status 2
    after cleanup.
\end{description}

The \cmdlineoption{--no-signals} option can be used to inhibit all signal
processing except for \const{SIGUSR2}. The handling of \const{SIGUSR2}
is vital for dealing with blocking system call in threads. The used
signal may be changed using the \cmdlineoption{--sigalert=NUM} option or
disabled using \verb$--sigalert=0$.



\section{Linking embedded applications using swipl-ld}	\label{sec:plld}

The utility program \program{swipl-ld} (Win32: swipl-ld.exe) may be used to link
a combination of C files and Prolog files into a stand-alone executable.
\program{swipl-ld} automates most of what is described in the previous
sections.

In normal usage, a copy is made of the default embedding template
\file{.../swipl/include/stub.c}. The main() routine is modified to suit
your application. PL_initialise() \strong{must} be passed the
program name (\arg{argv[0]}) (Win32: the executing program can be
obtained using GetModuleFileName()). The other elements of the
command line may be modified. Next, \program{swipl-ld} is typically invoked
as:

\begin{code}
swipl-ld -o output stubfile.c [other-c-or-o-files] [plfiles]
\end{code}

\program{swipl-ld} will first split the options into various groups for both
the C compiler and the Prolog compiler. Next, it will add various
default options to the C compiler and call it to create an executable
holding the user's C code and the Prolog kernel. Then, it will call the
SWI-Prolog compiler to create a saved state from the provided Prolog
files and finally, it will attach this saved state to the created
emulator to create the requested executable.

Below, it is described how the options are split and which additional
options are passed.

\begin{description}
    \cmdlineoptionitem{-help}{}
Print brief synopsis.
    \cmdlineoptionitem{-pl}{prolog}
Select the Prolog to use.  This Prolog is used for two purposes: get the
home directory as well as the compiler/linker options and create a saved
state of the Prolog code.
    \cmdlineoptionitem{-ld}{linker}
Linker used to link the raw executable.  Default is to use the C compiler
(Win32: \program{link.exe}).
    \cmdlineoptionitem{-cc}{C compiler}
Compiler for \fileext{c} files found on the command line.  Default is the
compiler used to build SWI-Prolog accessible through the Prolog flag
\prologflag{c_cc} (Win32: \program{cl.exe}).
    \cmdlineoptionitem{-c++}{C++-compiler}
Compiler for C++ source file (extensions \fileext{cpp}, \fileext{cxx},
\fileext{cc} or \fileext{C}) found on the command line.  Default is
\program{c++} or \program{g++} if the C compiler is \program{gcc}
(Win32: cl.exe).

    \cmdlineoptionitem{-nostate}{}
Just relink the kernel, do not add any Prolog code to the new kernel.
This is used to create a new kernel holding additional foreign predicates
on machines that do not support the shared-library (DLL) interface, or if
building the state cannot be handled by the default procedure used by
\program{swipl-ld}.  In the latter case the state is created separately and
appended to the kernel using \exam{cat <kernel> <state> > <out>}
(Win32: \exam{copy /b <kernel>+<state> <out>}).

    \cmdlineoptionitem{-shared}{}
Link C, C++ or object files into a shared object (DLL) that can be
loaded by the load_foreign_library/1 predicate. If used with
\cmdlineoption{-c}{} it sets the proper options to compile a C or C++
file ready for linking into a shared object.

    \cmdlineoptionitem{-dll}{}
\emph{Windows only}. Embed SWI-Prolog into a DLL rather than an
executable.

    \cmdlineoptionitem{-c}{}
Compile C or C++ source files into object files. This turns
\program{swipl-ld} into a replacement for the C or C++ compiler, where proper
options such as the location of the include directory are passed
automatically to the compiler.

    \cmdlineoptionitem{-E}{}
Invoke the C preprocessor. Used to make \program{swipl-ld} a replacement for
the C or C++ compiler.

    \cmdlineoptionitem{-pl-options}{,\ldots}
Additional options passed to Prolog when creating the saved state.  The
first character immediately following \const{pl-options} is used as
separator and translated to spaces when the argument is built.
Example: \exam{-pl-options,-F,xpce} passes \exam{-F xpce} as additional
flags to Prolog.
    \cmdlineoptionitem{-ld-options}{,\ldots}
Passes options to the linker, similar to \cmdlineoption{-pl-options}.
    \cmdlineoptionitem{-cc-options}{,\ldots}
Passes options to the C/C++ compiler, similar to \cmdlineoption{-pl-options}.
    \cmdlineoptionitem{-v}{}
Select verbose operation, showing the various programs and their options.
    \cmdlineoptionitem{-o}{outfile}
Reserved to specify the final output file.
    \cmdlineoptionitem*{-l}{library}
Specifies a library for the C compiler.  By default, \clib{-lswipl}
(Win32: libpl.lib) and the libraries needed by the Prolog kernel are given.
    \cmdlineoptionitem*{-L}{library-directory}
Specifies a library directory for the C compiler.  By default the
directory containing the Prolog C library for the current architecture
is passed.
    \cmdlineoptionitem{\cmdlineoption{-g} \bnfor{}
		       \cmdlineoption{-I\arg{include-directory}} \bnfor{}
		       \cmdlineoption{-D\arg{definition}}}{}
These options are passed to the C compiler.  By default, the include
directory containing \file{SWI-Prolog.h} is passed.  \program{swipl-ld} adds
two additional \argoption*{-D}{def} flags:
\begin{description}
\cmdlineoptionitem*{-D}{\const{__SWI_PROLOG__}}
Indicates the code is to be connected to SWI-Prolog.
\cmdlineoptionitem*{-D}{\const{__SWI_EMBEDDED__}}
Indicates the creation of an embedded program.
\end{description}
    \cmdlineoptionitem{}{*.o \bnfor{}
			 *.c \bnfor{}
			 *.C \bnfor{}
			 *.cxx \bnfor{}
			 *.cpp}
Passed as input files to the C compiler.
    \cmdlineoptionitem{}{*.pl \bnfor *.qlf}
Passed as input files to the Prolog compiler to create the saved state.
    \cmdlineoptionitem{}{*}
All other options. These are passed as linker options to the
C compiler.
\end{description}


\subsection{A simple example}
\label{sec:foreign-example}

The following is a very simple example going through all the steps
outlined above. It provides an arithmetic expression evaluator. We will
call the application \program{calc} and define it in the files \file{calc.c}
and \file{calc.pl}.  The Prolog file is simple:

\begin{code}
calc(Atom) :-
        term_to_atom(Expr, Atom),
        A is Expr,
        write(A),
        nl.
\end{code}

The C part of the application parses the command line options,
initialises the Prolog engine, locates the \verb$calc/1$ predicate and calls
it.  The coder is in \figref{calc}.

\begin{figure}
\begin{code}
#include <stdio.h>
#include <string.h>
#include <SWI-Prolog.h>

#define MAXLINE 1024

int
main(int argc, char **argv)
{ char expression[MAXLINE];
  char *e = expression;
  char *program = argv[0];
  char *plav[2];
  int n;

  /* combine all the arguments in a single string */

  for(n=1; n<argc; n++)
  { if ( n != 1 )
      *e++ = ' ';
    strcpy(e, argv[n]);
    e += strlen(e);
  }

  /* make the argument vector for Prolog */

  plav[0] = program;
  plav[1] = NULL;

  /* initialise Prolog */

  if ( !PL_initialise(1, plav) )
    PL_halt(1);

  /* Lookup calc/1 and make the arguments and call */

  { predicate_t pred = PL_predicate("calc", 1, "user");
    term_t h0 = PL_new_term_refs(1);
    int rval;

    PL_put_atom_chars(h0, expression);
    rval = PL_call_predicate(NULL, PL_Q_NORMAL, pred, h0);

    PL_halt(rval ? 0 : 1);
  }

  return 0;
}
\end{code}
\caption{C source for the calc application}
\label{fig:calc}
\end{figure}

\noindent
The application is now created using the command line below.  The option
\exam{-goal true} sets the Prolog initialization goal to suppress the
banner. Note that the \exam{-o calc} does not specify an extension. If
the platform uses a file extension for executables, \program{swipl-ld}
will add this (e.g., \fileext{exe} on Windows).

\begin{code}
% swipl-ld -goal true -o calc calc.c calc.pl
\end{code}

\noindent
The created program \program{calc} is a native executable with the
Prolog code attached to it.  Note that the program typically depends
on the shared object \file{libswipl} and, depending on the platform
and configuration, on several external shared objects.

\begin{code}
% ./calc pi/2
1.5708
\end{code}


\section{The Prolog `home' directory}		\label{sec:findhome}

Executables embedding SWI-Prolog should be able to find the `home'
directory of the development environment unless a self-contained
saved state has been added to the executable (see qsave_program/[1,2]
and \secref{plld}).

If Prolog starts up, it will try to locate the development environment.
To do so, it will try the following steps until one succeeds:

\begin{enumerate}
    \item If the \cmdlineoption{--home=DIR} is provided, use this.
    \item If the environment variable \env{SWI_HOME_DIR} is defined and
          points to an existing directory, use this.
    \item If the environment variable \env{SWIPL} is defined and
          points to an existing directory, use this.
    \item Locate the primary executable or (Windows only) a component
          (\jargon{module}) thereof and check whether the parent
	  directory of the directory holding this file contains the
	  file \file{swipl}.  If so, this file contains the (relative)
	  path to the home directory. If this directory exists, use
	  this.  This is the normal mechanism used by the binary
	  distribution.
    \item If the precompiled path exists, use it.  This is only useful
          for a source installation.
\end{enumerate}

If all fails and there is no state attached to the executable or
provided Windows module (see PL_initialise()), SWI-Prolog gives up.  If
a state is attached, the current working directory is used.

The file_search_path/2 alias \const{swi} is set to point to the home
directory located.


\section{Example of Using the Foreign Interface} \label{sec:foreignxmp}

Below is an example showing all stages of the declaration of a foreign
predicate that transforms atoms possibly holding uppercase letters into
an atom only holding lowercase letters. \Figref{lowercase-c} shows the
C source file, \figref{load-foreign} illustrates compiling and loading
of foreign code.

\begin{figure}[htb]

\begin{code}
/*  Include file depends on local installation */
#include <SWI-Prolog.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>

foreign_t
pl_lowercase(term_t u, term_t l)
{ char *copy;
  char *s, *q;
  int rval;

  if ( !PL_get_atom_chars(u, &s) )
    return PL_warning("lowercase/2: instantiation fault");
  copy = malloc(strlen(s)+1);

  for( q=copy; *s; q++, s++)
    *q = (isupper(*s) ? tolower(*s) : *s);
  *q = '\0';

  rval = PL_unify_atom_chars(l, copy);
  free(copy);

  return rval;
}

install_t
install()
{ PL_register_foreign("lowercase", 2, pl_lowercase, 0);
}
\end{code}

    \caption{Lowercase source file}
    \label{fig:lowercase-c}
\end{figure}


\begin{figure}[htb]
\begin{code}
% gcc -I/usr/local/lib/swipl-\plversion/include -fpic -c lowercase.c
% gcc -shared -o lowercase.so lowercase.o
% swipl
Welcome to SWI-Prolog (...)
...

1 ?- load_foreign_library(lowercase).
true.

2 ?- lowercase('Hello World!', L).
L = 'hello world!'.
\end{code}
    \caption{Compiling the C source and loading the object file}
    \label{fig:load-foreign}
\end{figure}
\clearpage


\section{Notes on Using Foreign Code}	\label{sec:foreignnotes}

\subsection{Foreign debugging functions}
\label{sec:foreign-debug}

The functions in this section are primarily intended for debugging
foreign extensions or embedded Prolog. Violating the constraints of the
foreign interface often leads to crashes in a subsequent garbage
collection. If this happens, the system needs to be compiled for
debugging using \exam{cmake -DCMAKE_BUILD_TYPE=Debug}, after which all
functions and predicates listed below are available to use from the
debugger (e.g. \program{gdb}) or can be placed at critical location in
your code or the system code.

\begin{description}
    \cfunction{void}{PL_backtrace}{int depth, int flags}
Dump a Prolog backtrace to the \const{user_error} stream. \arg{Depth} is
the number of frames to dump. \arg{Flags} is a bitwise or of the
following constants:

    \begin{description}
    \termitem{PL_BT_SAFE}{}
    (0x1) Do not try to print \jargon{goals}.  Instead, just print the
    predicate name and arity.  This reduces the likelihood to crash if
    PL_backtrace() is called in a damaged environment.
    \termitem{PL_BT_USER}{}
    (0x2) Only show `user' frames.  Default is to also show frames
    of hidden built-in predicates.
    \end{description}

    \cfunction{char *}{PL_backtrace_string}{int depth, int flags}
As PL_backtrace(), but returns the stack as a string. The string uses
UTF-8 encoding. The returned string must be freed using PL_free(). This
function is was added to get stack traces from running servers where I/O
is redirected or discarded.  For example, using \program{gdb}, a stack
trace is printed in the gdb console regardless of Prolog I/O redirection
using the following command:

\begin{code}
(gdb) printf "%s", PL_backtrace_string(25,0)
\end{code}

The source distribution provides the script \file{scripts/swipl-bt} that
exploits \program{gdb} and PL_backtrace_string() to print stack traces
in various formats for a SWI-Prolog process, given its process id.

    \cfunction{int}{PL_check_data}{term_t data}
    Check the consistency of the term \arg{data}.  Returns \const{TRUE}
    this is actually implemented in the current version and
    \const{FALSE} otherwise.  The actual implementation only exists
    if the system is compiled with the cflag \const{-DO_DEBUG} or
    \const{-DO_MAINTENANCE}.  This is \emph{not} the default.

    \cfunction{int}{PL_check_stacks}{}
    Check the consistency of the runtime stacks of the calling thread.
    Returns \const{TRUE} this is actually implemented in the current
    version and \const{FALSE} otherwise. The actual implementation only exists
    if the system is compiled with the cflag \const{-DO_DEBUG} or
    \const{-DO_MAINTENANCE}.  This is \emph{not} the default.
\end{description}

The Prolog kernel sources use the macro \cfuncref{DEBUG}{Topic, Code}.
These macros are disabled in the production version and must be enabled
by recompiling the system as described above. Specific topics can be
enabled and disabled using the predicates prolog_debug/1 and
prolog_nodebug/1. In addition, they can be activated from the
commandline using commandline option \const{-d topics}, where
\arg{topics} is a comma-separated list of debug topics to enable. For
example, the code below adds many consistency checks and prints messages
if the Prolog signal handler dispatches signals.

\begin{code}
$ swipl -d chk_secure,msg_signal
\end{code}

\begin{description}
    \predicate{prolog_debug}{1}{+Topic}
    \nodescription
    \predicate{prolog_nodebug}{1}{+Topic}
Enable/disable a debug topic.  \arg{Topic} is an atom that identifies
the desired topic. The available topics are defined in
\file{src/pl-debug.h}.  Please search the sources to find out what
is actually printed and when.  We highlight one topic here:

    \begin{description}
    \termitem{chk_secure}
    Add many expensive consistency checks to the system.  This should
    typically be used when the system crashes, notably in the garbage
    collector.  Garbage collection crashes are in most cases caused
    by invalid data on the Prolog stacks.  This debug topic may help
    locating how the invalid data was created.
    \end{description}

These predicates require the system to be compiled for debugging using
\exam{cmake -DCMAKE_BUILD_TYPE=Debug}.

    \cfunction{int}{PL_prolog_debug}{const char *topic}
    \nodescription
    \cfunction{int}{PL_prolog_nodebug}{const char *topic}
(De)activate debug topics. The \arg{topics} argument is a
comma-separated string of topics to enable or disable. Matching is
case-insensitive.  See also prolog_debug/1 and prolog_nodebug/1.

These functions require the system to be compiled for debugging using
\exam{cmake -DCMAKE_BUILD_TYPE=Debug}.

\end{description}


\subsection{Memory Allocation}
\label{sec:foreign-malloc}

SWI-Prolog's heap memory allocation is based on the \manref{malloc}{3}
library routines. SWI-Prolog provides the functions below as a wrapper
around malloc(). Allocation errors in these functions trap SWI-Prolog's
fatal-error handler, in which case PL_malloc() or PL_realloc() do not
return.

Portable applications must use PL_free() to release strings returned
by PL_get_chars() using the \const{BUF_MALLOC} argument.  Portable
applications may use both PL_malloc() and friends or malloc() and
friends but should not mix these two sets of functions on the same
memory.

\begin{description}
    \cfunction{void *}{PL_malloc}{size_t bytes}
Allocate \arg{bytes} of memory.  On failure SWI-Prolog's fatal-error
handler is called and PL_malloc() does not return.  Memory allocated
using these functions must use PL_realloc() and PL_free() rather than
realloc() and free().

    \cfunction{void *}{PL_realloc}{void *mem, size_t size}
Change the size of the allocated chunk, possibly moving it.  The
\arg{mem} argument must be obtained from a previous PL_malloc() or
PL_realloc() call.

    \cfunction{void}{PL_free}{void *mem}
Release memory.  The \arg{mem} argument must be obtained from a
previous PL_malloc() or PL_realloc() call.
\end{description}

\subsection{Compatibility between Prolog versions}
\label{sec:foreign-compat}

Great care is taken to ensure binary compatibility of foreign extensions
between different Prolog versions. Only the much less frequently used stream
interface has been responsible for binary incompatibilities.

\index{PLVERSION}%
Source code that relies on new features of the foreign interface can
use the macro \const{PLVERSION} to find the version of
\file{SWI-Prolog.h} and PL_query() using the option
\const{PL_QUERY_VERSION} to find the version of the attached Prolog
system. Both follow the same numbering schema explained with PL_query().


\subsection{Foreign hash tables}
\label{sec:foreign-hash-tables}

As of SWI-Prolog 8.3.2 the foreign API provides access to the internal
thread-safe and lock-free hash tables that associate pointers or objects
that fit in a pointer such as atoms (\ctype{atom_t}). An argument
against providing these functions is that they have little to do with
Prolog. The argument is favor is that it is hard to implement efficient
lock-free tables without low-level access to the underlying Prolog
threads and exporting this interface has a low cost.

The functions below \textbf{can only be called if the calling thread is
associated with a Prolog thread}. Failure to do so causes the call to be
ignored or return the failure code where applicable.

\begin{description}
    \cfunction{hash_table_t}{PL_new_hash_table}{int size,
						void (*free_symbol)(void *n, void *v)}
Create a new table for \arg{size} key-value pairs. The table is resized
when needed. If you know the table will hold 10,000 key-value pairs,
providing a suitable initial size avoids resizing.  The \arg{free_symbol}
function is called whethever a key-value pair is removed from the table.
This can be \const{NULL}.

    \cfunction{int}{PL_free_hash_table}{hash_table_t table}
Destroy the hash table.  First calls PL_clear_hash_table().

    \cfunction{void*}{PL_lookup_hash_table}{hash_table_t table, void *key}
Return the value matching \arg{key} or \const{NULL} if \arg{key} does not
appear in the table.

    \cfunction{void*}{PL_add_hash_table}{hash_table_t table,
					 void *key, void *value, int flags}
Add \arg{key}-\arg{value} to the table. The behaviour if \arg{key} is
already in the table depends on \arg{flags}. If \const{0}, this function
returns the existing value without updating the table. If
\const{PL_HT_UPDATE} the old \arg{value} is \emph{replaced} and the
function returns the old value. If \const{PL_HT_NEW}, a message and
backtrace are printed and the function returns \arg{NULL} if \arg{key}
is already in the table.

    \cfunction{void*}{PL_del_hash_table}{hash_table_t table, void *key}
Delete \arg{key} from the table, returning the old associated value or
\const{NULL}

    \cfunction{int}{PL_clear_hash_table}{hash_table_t table}
Delete all key-value pairs from the table.  Call \arg{free_symbol} for
each deleted pair.

    \cfunction{hash_table_enum_t}{PL_new_hash_table_enum}{hash_table_t table}
Return a table \jargon{enumerator} (cursor) that can be used to
enumerate all key-value pairs using PL_advance_hash_table_enum(). The
enumerator must be discarded using PL_free_hash_table_enum(). It is safe
for another thread to add symbols while the table is being enumerated,
but undefined whether or not these new symbols are visible. If another
thread deletes a key that is not yet enumerated it will not be
enumerated.

    \cfunction{void}{PL_free_hash_table_enum}{hash_table_enum_t e}
Discard an enumerator object created using PL_new_hash_table_enum().
Failure to do so causes the table to use more and more memory on
subsequent modifications.

    \cfunction{int}{PL_advance_hash_table_enum}{hash_table_enum_t e,
						void **key, void **value}
Get the next key-value pair from a cursor.
\end{description}

\subsection{Debugging and profiling foreign code (valgrind)}
\label{sec:foreign-debug-and-profile}

\index{valgrind}\index{profiling,foreign code}%
This section is only relevant for Unix users on platforms supported by
\href{http://valgrind.org/}{valgrind}. Valgrind is an excellent binary
instrumentation platform.  Unlike many other instrumentation platforms,
valgrind can deal with code loaded through dlopen().

The \program{callgrind} tool can be used to profile foreign code loaded
under SWI-Prolog. Compile the foreign library adding \cmdlineoption{-g}
option to \program{gcc} or \program{swipl-ld}. By setting the environment
variable \env{VALGRIND} to \const{yes}, SWI-Prolog will \emph{not}
release loaded shared objects using dlclose(). This trick is required to
get source information on the loaded library. Without, valgrind claims
that the shared object has no debugging information.\footnote{Tested
using valgrind version 3.2.3 on x64.} Here is the complete sequence
using \program{bash} as login shell:

\begin{code}
% VALGRIND=yes valgrind --tool=callgrind pl <args>
<prolog interaction>
% kcachegrind callgrind.out.<pid>
\end{code}

\subsection{Name Conflicts in C modules}
\label{sec:foreign-name-conflicts}

In the current version of the system all public C functions of
SWI-Prolog are in the symbol table.  This can lead to name clashes with
foreign code.  Someday I should write a program to strip all these
symbols from the symbol table (why does Unix not have that?).  For now
I can only suggest you give your function another name.  You can do this
using the C preprocessor.  If---for example---your foreign package uses
a function warning(), which happens to exist in SWI-Prolog as well, the
following macro should fix the problem:

\begin{code}
#define warning warning_
\end{code}

Note that shared libraries do not have this problem as the shared
library loader will only look for symbols in the main executable for
symbols that are not defined in the library itself.


\subsection{Compatibility of the Foreign Interface}
\label{sec:foreign-quintus-sicstus}

The term reference mechanism was first used by Quintus Prolog version~3.
SICStus Prolog version 3 is strongly based on the Quintus interface. The
described SWI-Prolog interface is similar to using the Quintus or
SICStus interfaces, defining all foreign-predicate arguments of type
\const{+term}.  SWI-Prolog explicitly uses type \ctype{functor_t}, while
Quintus and SICStus use <name> and <arity>.  As the names of the functions
differ from Prolog to Prolog, a simple macro layer dealing with the
names can also deal with this detail.  For example:

\begin{code}
#define QP_put_functor(t, n, a) \
	PL_put_functor(t, PL_new_functor(n, a))
\end{code}

The {\tt PL_unify_*()} functions are lacking from the Quintus and
SICStus interface.  They can easily be emulated, or the put/unify
approach should be used to write compatible code.

The PL_open_foreign_frame()/PL_close_foreign_frame() combination is
lacking from both other Prologs.  SICStus has PL_new_term_refs(0),
followed by PL_reset_term_refs(), that allows for discarding
term references.

The Prolog interface for the graphical user interface package XPCE
shares about 90\% of the code using a simple macro layer to deal
with different naming and calling conventions of the interfaces.