\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 an query interface and
an interface to extract multiple solutions from an 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 three ways. Using 
\jargon{static linking}, the extensions, a small description file and the basic
SWI-Prolog object file 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 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 gets quickly smaller and
              this interface is difficult to port and slow, it is no
              longer described in this manual.  The best alternatively
              would be to use the \idx{dld} package on machines do
	      not have shared libraries}.

\subsection{What linking is provided?}

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 \const{open_shared_object} (see
current_prolog_flag/2). If this prolog-flag yields 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?}

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{plld} 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.


\section{Dynamic Linking of shared libraries}	\label{sec:dynstatic}

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 \fileext{so} file (see your C programmers
documentation on how to create a \fileext{so} file). This file is
attached to the current process and \arg{Handle} is unified with a
handle to the shared object. Equivalent to
\exam{open_shared_object(File, [global], Handle)}. See also
load_foreign_library/[1,2].

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

    \predicate{open_shared_object}{3}{+File, +Options, -Handle}
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}


\section{Using the library shlib for \fileext{DLL} and \fileext{so} files}
                                                         \label{sec:DLL}
                                                         \label{sec:shlib}

This section discusses the functionality of the (autoload) library
\file{shlib.pl}, providing an interface to shared libraries.   This
library can only be used if the prolog-flag \const{open_shared_object} is
enabled.

\begin{description}
    \predicate{load_foreign_library}{2}{+Lib, +Entry}
Search for the given foreign library and link it to the current
SWI-Prolog instance.  The library may be specified with or without the
extension.  First, absolute_file_name/3 is used to locate the file.  If
this succeeds, the full path is passed to the low-level function to open
the library.  Otherwise, the plain library name is passed, exploiting
the operating-system defined search mechanism for the shared library.
The file_search_path/2 alias mechanism defines the alias \const{foreign},
which refers to the directories \file{<plhome>/lib/<arch>} and
\file{<plhome>/lib}, in this order.

If the library can be loaded, the function called \arg{Entry} will be
called without arguments. The return value of the function is ignored.

The \arg{Entry} function will normally call PL_register_foreign() to
declare functions in the library as foreign predicates.
    \predicate{load_foreign_library}{1}{+Lib}
Equivalent to load_foreign_library/2. For the entry-point, this function
first identifies the `base-name' of the library, which is defined to be
the file-name with path nor extension.  It will then try the entry-point
\mbox{\const{install-}<base>}.  On failure it will try to function
install().  Otherwise no install function will be called.
    \predicate{unload_foreign_library}{1}{+Lib}
If the foreign library defines the function uninstall_<base>() or
uninstall(), this function will be called without arguments and its
return value is ignored. Next, abolish/2 is used to remove all known
foreign predicates defined in the library. Finally the library itself is
detached from the process.
    \predicate{current_foreign_library}{2}{-Lib, -Predicates}
Query the currently loaded foreign libraries and their predicates.  {\em
Predicates} is a list with elements of the form {\em Module:Head},
indicating the predicates installed with PL_register_foreign() when
the entry-point of the library was called.
\end{description}

\Figref{msgbox} connects a Windows message-box using a foreign
function.  This example was tested using Windows~NT and Microsoft Visual
C++ 2.0.

\begin{figure}[h]
\begin{code}
#include <windows.h>
#include <SWI-Prolog.h>

static foreign_t
pl_say_hello(term_t to)
{ char *a;

  if ( PL_get_atom_chars(to, &a) )
  { MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL);

    PL_succeed;
  }

  PL_fail;
}

install_t
install()
{ PL_register_foreign("say_hello", 1, pl_say_hello, 0);
}
\end{code}
    \caption{MessageBox() example in Windows~NT}
    \label{fig:msgbox}
\end{figure}


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

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

\begin{center}
\begin{tabular}{ll}
\file{\ldots/pl/runtime/<arch>/libpl.a}    & SWI-Library \\
\file{\ldots/pl/include/SWI-Prolog.h}      & Include file \\
\file{\ldots/pl/include/SWI-Stream.h}      & Stream I/O include file \\
\file{\ldots/pl/include/SWI-Exports}       & Export declarations (AIX only) \\
\file{\ldots/pl/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{\ldots/pl/include/stub.c}
may be copied to your project and modified to define the foreign
extensions.  Below is stub.c, modified to link the lowercase example
described later in this chapter:

\begin{code}
/*  Copyright (c) 1991 Jan Wielemaker. All rights reserved.
    jan@swi.psy.uva.nl

    Purpose: Skeleton for extensions
*/

#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_install_readline();                /* delete if not required */

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

Now, a new executable may be created by compiling this file and linking
it to 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 using the \program{plld} utility described in secref{plld}.


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

\subsection{Type \ctype{term_t}: a reference to a Prolog term}

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 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 the this document we use the
following notation for arguments of type term_t:

\begin{quote}
\begin{tabular}{lp{3.5in}}
\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}

\noindent
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 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 refs 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
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 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}

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
information necessary to perform its memory management without 
special precautions from the C-programmer.


\subsection{Other foreign interface types}

\begin{description}
    \item[atom_t]
An atom in Prologs 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 C a character string 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 loose their definition).
    \item[qid_t]
Query Identifier. Used by
PL_open_query()/PL_next_solution()/PL_close_query() to handle
backtracking from C.
    \item[fid_t]
Frame Identifier. Used by
PL_open_foreign_frame()/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}.
\end{description}

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

\subsection{Argument Passing and Control}

If Prolog encounters a foreign predicate at run time it will call a
function specified in the predicate definition of the foreign predicate.
The arguments $1, \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{void}{PL_succeed}{}
Succeed deterministically. PL_succeed is defined as
\exam{return \const{TRUE}}.
    \cmacro{void}{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_CUTTED})]
The choice point left by the foreign function has been destroyed by
a cut.  The foreign function is given the opportunity to clean the
environment.
\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{void}{PL_retry}{long}
The foreign function succeeds while leaving a choice point. On
backtracking over this goal the foreign function will be called again,
but the control argument now indicates it is a `Redo' call and the
macro PL_foreign_context() will return the handle passed via
PL_retry(). This handle is a 30 bits signed value (two bits are used
for status indication).

    \cmacro{void}{PL_retry_address}{void *}
As PL_retry(), but ensures an address as returned by malloc() is
correctly recovered by PL_foreign_context_address().

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

    \cmacro{long}{PL_foreign_context}{control_t}
Extracts the context from the context argument.  In 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} as \const{PL_CUTTED}).

    \cmacro{void *}{PL_foreign_context_address}{control_t}
Extracts an address as passed in by PL_retry_address().
\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_CUTTED} 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, foreign_t handle)
{ struct context * ctxt;

  switch( PL_foreign_control(handle) )
  { case PL_FIRST_CALL:
        ctxt = malloc(sizeof(struct context));
        ...
        PL_retry_address(ctxt);
    case PL_REDO:
        ctxt = PL_foreign_context_address(handle);
        ...
        PL_retry_address(ctxt);
    case PL_CUTTED:
        free(ctxt);
        PL_succeed;
  }
}
\end{code}
    \caption{Skeleton for non-deterministic foreign functions}
    \label{fig:nondetermf}
\end{figure}


\subsection{Atoms and functors}

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}).

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

    \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{int}{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 have 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 multi-threaded version (see \secref{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
		  detroy 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}

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}

\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_ge_t*()} 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}

\begin{tabular}{|p{\tableft}|p{3.5in}|}
\hline
\const{PL_VARIABLE} & An unbound variable. The value of term as such
		      is a unique identifier for the variable. \\
\const{PL_ATOM}     & A Prolog atom. \\
\const{PL_STRING}   & A Prolog string. \\
\const{PL_INTEGER}  & A Prolog integer. \\
\const{PL_FLOAT}    & A Prolog floating point number. \\
\const{PL_TERM}     & A compound term. Note that a list is a
		      compound term \functor{.}{2}. \\
\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_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_float}{term_t}
Returns non-zero if \arg{term} is a float.
\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 with functor ./2 or
the atom \const{[]}.
\cfunction{int}{PL_is_atomic}{term_t}
Returns non-zero if \arg{term} is atomic (not variable or compound).
\cfunction{int}{PL_is_number}{term_t}
Returns non-zero if \arg{term} is an integer or float.
\end{description}


\subsubsection{Reading data from a 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, int *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.  {\em
flags} is a bitwise disjunction from two groups of constants.  The
first specifies which term-types should converted and the second
how the argument is stored.  Below is a specification of these
constants.  \const{BUF_RING} implies, if the data is not static
(as from an atom), the data is copied to the next buffer from a
ring of 16 buffers.  This is a convenient way of converting
multiple arguments passed to a foreign predicate to C-strings.  If
BUF_MALLOC is used, the data must be freed using free() when not
needed any longer.

\begin{tabular}{|p{\tableft}|p{3.5in}|}
\hline
\const{CVT_ATOM}    & Convert if term is an atom \\
\const{CVT_STRING}  & Convert if term is a string \\
\const{CVT_LIST}    & Convert if term is a list of integers between
		      1 and 255 \\
\const{CVT_INTEGER} & Convert if term is an integer (using \const{\%d}) \\
\const{CVT_FLOAT}   & Convert if term is a float (using \const{\%f}) \\
\const{CVT_NUMBER}  & Convert if term is a integer or float \\
\const{CVT_ATOMIC}  & Convert if term is atomic \\
\const{CVT_VARIABLE}& Convert variable to print-name \\
\const{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_RING}
		      is implied. \\
\const{CVT_ALL}     & Convert if term is any of the above, except for
                      \const{CVT_VARIABLE} and \const{CVT_WRITE} \\
\hline
\const{BUF_DISCARDABLE}     & Data must copied immediately \\
\const{BUF_RING}    & Data is stored in a ring of buffers \\
\const{BUF_MALLOC}  & Data is copied to a new buffer returned by
		      \manref{malloc}{3} \\
\hline
\end{tabular}
\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 no 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, assign its value over \arg{i}.  Note
that Prolog integers have limited value-range.  If \arg{t} is a floating
point number that can be represented as a long, this function succeeds
as well.
\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()/PL_get_pointer()
guarantees 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 or integer, its value is assigned over \arg{f}.
\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, int *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().
\cfunction{int}{PL_get_module}{term_t +t, module_t *module}
If \arg{t} is an atom, the system will lookup or create the
corresponding module and assign an opaque pointer to it over {\em
module},.
\cfunction{int}{PL_get_arg}{int index, term_t +t, term_t -a}
If \arg{t} is compound and index is between 1 and arity (including),
assign \arg{a} with a term-reference to the argument.
\cfunction{int}{_PL_get_arg}{int index, term_t +t, term_t -a}
Same as PL_get_arg(), but no checking is performed, nor whether \arg{t}
is actually a term, nor whether \arg{index} is a valid argument-index.
\end{description}


\subsubsection{Exchanging text using length and string}

All internal text-representation of 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, unsigned int len, char **s}
    \cfunction{int}{PL_get_list_nchars}{term_t t, unsigned int len, char **s}
    \cfunction{int}{PL_get_nchars}{term_t t, unsigned int len, char **s,
				   unsigned int flags}
    \cfunction{int}{PL_put_atom_nchars}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_put_string_nchars}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_put_list_ncodes}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_put_list_nchars}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_unify_atom_nchars}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_unify_string_nchars}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_unify_list_ncodes}{term_t t, unsigned int len, const char *s}
    \cfunction{int}{PL_unify_list_nchars}{term_t t, unsigned int len, const char *s}
\end{description}

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

\begin{description}
    \cfunction{atom_t}{PL_new_atom_nchars}{unsigned int len, const char *s}
Create a new atom as PL_new_atom(), but from length and characters.
    \cfunction{const char *}{PL_atom_nchars}{atom_t a, unsigned int *len}
Extract text and length of an atom.
\end{description}


\subsubsection{Reading a list}

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

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

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

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

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


\begin{description}
\cfunction{int}{PL_get_list}{term_t +l, term_t -h, term_t -t}
If \arg{l} is a list and not \const{[]} 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 \const{[]} 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 \const{[]} assign a term-reference to the
tail to \arg{t}.
\cfunction{int}{PL_get_nil}{term_t +l}
Succeeds if {\em} represents the atom \const{[]}.
\end{description}


\subsubsection{An example: defining write/1 in C}

\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}

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.  The new variable lives on the global
stack.  Note that the initial variable lives on the local stack and is
lost after a write to the term-references.  After using this function,
the variable will continue to live.
\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_atom_chars}{term_t -t, const char *chars}
Put an atom in the term-reference constructed from the 0-terminated
string.  The string itself will never be references by Prolog after this
function.
\cfunction{void}{PL_put_string_chars}{term_t -t, const char *chars}
Put a zero-terminated string in the term-reference. The data will be
copied.  See also PL_put_string_nchars().
\cfunction{void}{PL_put_string_nchars}{term_t -t,
				       unsigned int 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{void}{PL_put_list_chars}{term_t -t, const char *chars}
Put a list of ASCII values in the term-reference.
\cfunction{void}{PL_put_integer}{term_t -t, long i}
Put a Prolog integer in the term reference.
\cfunction{void}{PL_put_pointer}{term_t -t, void *ptr}
Put a Prolog integer in the term-reference.  Provided ptr is in the
`malloc()-area', PL_get_pointer() will get the pointer back.
\cfunction{void}{PL_put_float}{term_t -t, double f}
Put a floating-point value in the term-reference.
\cfunction{void}{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{void}{PL_put_list}{term_t -l}
Same as \exam{PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2))}.
\cfunction{void}{PL_put_nil}{term_t -l}
Same as \exam{PL_put_atom_chars("[]")}.
\cfunction{void}{PL_put_term}{term_t -t1, term_t +t2}
Make \arg{t1} point to the same term as \arg{t2}.
\cfunction{void}{PL_cons_functor}{term_t -h, functor_t f, \ldots}
Create a term, whose arguments are filled from variable argument list
holding the same number of term_t objects as the arity of the functor.
To create the term \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{void}{PL_cons_functor_v}{term_t -h, functor_t f, term_t a0}
Creates 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{void}{PL_cons_list}{term_t -l, term_t +h, term_t +t}
Create a list (cons-) cell in \arg{l} from the head and tail.  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.
\end{description}


\subsection{Unifying data}

The functions of this sections \jargon{unify} terms with other terms or
translated C-data structures. Except for PL_unify(), the functions of
this section are specific to SWI-Prolog. They have been introduced to
make translation of old code easier, but also because they provide for
a faster mechanism for returning data to Prolog that requires less
term-references.  Consider the case where we want a foreign function
to return the host name of the machine Prolog is running on.  Using
the {\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, buf);
  }

  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}


\begin{description}
\cfunction{int}{PL_unify}{term_t ?t1, term_t ?t2}
Unify two Prolog terms and return non-zero on success.
\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_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{void}{PL_unify_string_nchars}{term_t ?t,
					 unsigned int len,
					 const char *chars}
Unify \arg{t} with a Prolog string object created from the string
created from the \arg{len}/\arg{chars} pair. The data will be copied.
This interface can deal with 0-bytes in the string. See also
\secref{foreigndata}.
\cfunction{int}{PL_unify_integer}{term_t ?t, long n}
Unify \arg{t} with a Prolog integer from \arg{n}.
\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 fails.
Not that this function does not create a term if the argument is
already instantiated.
\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 to \arg{h} and a reference
to the tail of the list in \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
is a sequence of a type identifier, followed by the required
arguments. This predicate is an extension to the Quintus and SICStus
foreign interface from which the SWI-Prolog foreign interface has been
derived, but has proved to be a powerful and comfortable way to create
compound terms from C.  Due to the vararg packing/unpacking and the
required type-switching this interface is slightly slower than using
the primitives.  Please note that some bad C-compilers have fairly
low limits on the number of arguments that may be passed to a function.

Special attention is required when passing numbers. C `promotes' any
integral smaller than \type{int} to \type{int}. I.e.\ 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. Upto 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. Similar, 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_ATOM} \arg{atom_t}}
Unify the argument with an atom, as in PL_unify_atom().
   \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_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_INTEGER} \arg{long}}
Unify the argument with an integer, as in PL_unify_integer().
   \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 the return value of a PL_new_term_ref()
call to get access to a variable.
   \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_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 following 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 build 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_string_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}

\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_RING}
    argument of PL_get_chars();

    In the current implementation, the string is surrounded by
    \arg{chr} and any occurence of \arg{chr} is doubled.  In the
    future the behaviour will depend on the \const{character_escape}
    prolog-flag.  See current_prolog_flag/2.
\end{description}


\subsection{Calling Prolog from C}

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


\subsubsection{Predicate references}

This section discusses the functions used to communicate about
predicates. Though a Prolog predicate may defined or not, redefined,
etc., a Prolog predicate has a handle that is not destroyed, nor moved.
This handle is known by the type \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.
\cfunction{predicate_t}{PL_predicate}{const char *name, int arity, const char* module}
Same a PL_pred(), but provides a more convenient interface to
the C-programmer.
\cfunction{void}{PL_predicate_info}{predicate_t p, atom_t *n, int *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 was imported into
the module given to PL_predicate(), this function will return the
module where the predicate was defined.
\end{description}


\subsubsection{Initiating a query from C}

This section discusses the functions for creating and manipulating
queries from C.  Note that a foreign context can have at most one
active query.  This implies it is allowed to make strictly nested
calls between C and Prolog (Prolog calls C, calls Prolog, calls C,
etc., but it is \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. This function always
succeeds, regardless whether the predicate is defined or not. \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{module_transparent} predicates.
See 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 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.
\end{description}

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

\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{void}{PL_cut_query}{qid}
Discards the query, but does not delete any of the data created by the
query.  It just invalidate \arg{qid}, allowing for a new call to
PL_open_query() in this context.
    \cfunction{void}{PL_close_query}{qid}
As PL_cut_query(), but all data and bindings created by the query are
destroyed.
    \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, module_t}
Call term just like the Prolog predicate once/1. \arg{Term} is called
in the specified module, or in the context module if module_t = 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}

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

\begin{description}
\cfunction{fid_t}{PL_open_foreign_frame}{}
Created a foreign frame, holding a mark that allows the system to
undo bindings and destroy data created after it as well as providing
the environment for creating term-references.  This function is called
by the kernel before calling a foreign predicate.
\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 does not pop the frame.  I.e.\ the same frame
can be rewinded 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{Foreign Code and 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 inner most module is returned
via \arg{module *}. If \arg{raw} is not a module construct \arg{arg}
will simply be put in \arg{plain}. If \arg{module *} is \const{NULL} it
will be set to the context module. Otherwise it will be left untouched.
The following example shows how to obtain the plain term and module if
the default module is the user module:


\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}
Return the name of \arg{module} as an atom.
\cfunction{module_t}{PL_new_module}{atom_t name}
Find an existing or create a new module with name specified by the atom
\arg{name}.
\end{description}


\subsection{Prolog exceptions in foreign code}

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

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

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

If a C-function, implementing a predicate calls Prolog and detects
an exception using PL_exception(), it can handle this exception, or
return with the exception.  Some caution is required though.  It is
\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 arithmethic_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);			/* donot 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 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.%
    \footnote{This interface differs in two ways from Quintus.  The
	      calling predicates simp,y signal failure if an exception
	      was raised, and a term referenced is returned, rather 
	      passed and filled with the error term.   Exceptions
	      can only be handled using the PL_next_solution() interface,
	      as a handle to the query is required}.
\end{description}


\subsection{Foreign code and Prolog threads}

If SWI-Prolog has been build to support multi-threading (see
\secref{threads}), all foreign-code linked to Prolog should be
thread-safe (\jargon{reentrant}) or guarded in Prolog using with_mutex/2
from simultaneous access from multiple Prolog threads.  On Unix systems,
this generally implies the code should be compiled with the
\const{-D_REENTRANT} flag passed to the compiler.  Please note that on
many Unix systems not all systemcalls and library-functions are
thread-safe.  Consult your manual for details.

If you are using SWI-Prolog as an embedded engine in a multi-threaded
application you can access the Prolog engine from multiple threads by
creating an \jargon{engine} in each thread from which you call Prolog.
Without creating an engine, a thread can only use functions that do
not use the \type{term_t} type (for example PL_new_atom()).

{\bf Please note that the interface below will only work if threading
in your application is based on the same thread-library as used to
compile SWI-Prolog.}


\begin{description}
    \cfunction{int}{PL_thread_self}{}
Returns the integer Prolog identifier of the engine or -1 if the calling
thread has no Prolog engine.  This function is also provided in the
single-threaded version of SWI-Prolog, where it returns -2.
    \cfunction{int}{PL_thread_attach_engine}{PL_thread_attr_t *attr}
Creates a new Prolog engine in the calling thread. If the calling thread
already has an engine the reference count of the engine is incremented.
The \arg{attr} argument can be \const{NULL} to create a thread with
default attributes.  Otherwise it is a pointer to a structure with
the definition below.  For any field with value `0', the default is
used.

\begin{code}
typedef struct
{ unsigned long	    local_size;	   /* Stack sizes (K-bytes) */
  unsigned long	    global_size;
  unsigned long	    trail_size;
  unsigned long	    argument_size;
  char *	    alias;	   /* alias name */
} PL_thread_attr_t;
\end{code}

The structure may be destroyed after PL_thread_attach_engine() has
returned. If an error occurs, -1 is returned. If this Prolog is not
compiled for multi-threading, -2 is returned. 
    \cfunction{int}{PL_thread_destroy_engine}{}
Destroy the Prolog engine in the calling thread. Only takes effect if
PL_thread_destroy_engine() is called as many times as
PL_thread_attach_engine() in this thread.  Returns \const{TRUE} on
success and \const{FALSE} if the calling thread has no engine or this
Prolog does not support threads.

Please note that construction and destruction of engines are
relatively expensive operations. Only destroy an engine if performance
is not critical and memory is a critical resource. The engine is
automatically destroyed if the thread finishes, regardless how many
times PL_thread_attach_engine() has been called.
\end{description}


\subsection{Miscellaneous}

\subsubsection{Term Comparison}

\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}

In some applications it is useful to store and retreive 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{void}{PL_recorded}{record_t record, term_t -t}
    Copy a recorded term back to the Prolog stack.  The same record
    may be used to copy multiple instances at any time to the Prolog
    stack.  See also PL_record() and PL_erase().
\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 an 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 0-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, unsigned int *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() 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}


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

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

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

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


\subsection{Errors and warnings}

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}

\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 in \tabref{action}.

\begin{table}
\begin{quote}\begin{tabular}{|p{\tableft}|p{3.5in}|}
\hline
\const{PL_ACTION_TRACE}     & Start Prolog tracer (trace/0).
			      Requires no arguments. \\
\const{PL_ACTION_DEBUG}     & Switch on Prolog debug mode (debug/0).
			      Requires no arguments. \\
\const{PL_ACTION_BACKTRACE} & Print backtrace on current output stream.
                              The argument (an int) is the number of frames
			      printed. \\
\const{PL_ACTION_HALT}      & Halt Prolog execution. This action should be
                              called rather than Unix exit() to give Prolog
                              the opportunity to clean up. This call does
                              not return. The argument (an int) is the 
			      exit code. See halt/1. \\
\const{PL_ACTION_ABORT}     & Generate a Prolog abort (abort/0).
			      This call does not return.
			      Requires no arguments. \\
\const{PL_ACTION_BREAK}     & Create a standard Prolog break environment
			      (break/0). Returns after the user types
			      the end-of-file character.
			      Requires no arguments. \\
\const{PL_ACTION_GUIAPP}    & Win32: Used to indicate the kernel that the
			      application is a GUI application if the
			      argument is not 0 and a console
			      application if the argument is 0.
			      If a fatal error occurs, the system uses a
			      windows messagebox to report this on a GUI
			      application and simply prints the error
			      and exits otherwise. \\
\const{PL_ACTION_WRITE}	    & Write the argument, a \ctype{char *} to the
			      current output stream. \\
\const{PL_ACTION_FLUSH}	    & Flush the current output stream.
			      Requires no arguments. \\
\hline
\end{tabular}\end{quote}

    \caption{PL_action() options}
    \label{tab:action}
\end{table}
\end{description}

\subsection{Querying Prolog}

\begin{description}
\cfunction{C_type}{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. The  options are given in \tabref{query}.


\begin{table}
\begin{quote}\begin{tabular}{|p{\tableft}|p{3.5in}|}
\hline
\const{PL_QUERY_ARGC}       & Return an integer holding the number of
                              arguments given to Prolog from Unix. \\
\const{PL_QUERY_ARGV}       & Return a char ** holding the argument vector
                              given to Prolog from Unix. \\
\const{PL_QUERY_SYMBOLFILE} & Return a 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}. \\
\hline
\end{tabular}\end{quote}

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

\subsection{Registering Foreign Predicates}


\begin{description}
\cfunction{int}{PL_register_foreign}{const char *name, int arity,
				     foreign_t (*function)(), int flags}
Register a C-function to implement a Prolog predicate. After this call
returns successfully a predicate with name \arg{name} (a char *) and
arity \arg{arity} (a C int) is created. As a special case, \arg{name}
may consist of a sequence of alpha-numerical characters followed by the
colon (\const{:}). In this case the name uptil the colon is taken to be
the destination module and the rest of the name the predicate name.

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

\begin{tabular}{|p{\tableft}|p{3.5in}|}
\hline
\const{PL_FA_NOTRACE}          & Predicate cannot be seen in the tracer \\
\const{PL_FA_TRANSPARENT}      & Predicate is module transparent \\
\const{PL_FA_NONDETERMINISTIC} & Predicate is non-deterministic.
                                 See also PL_retry(). \\
\const{PL_FA_VARARGS}	       & Use alternative calling convention. \\
\hline
\end{tabular}

    \cfunction{void}{PL_load_extensions}{PL_extension *e}
Register foreign predicates from a table of structures. This is an
alternative to multiple calls to PL_register_foreign() and simplifies
code that wishes to use PL_register_extensions() as an alternative.
The type \ctype{PL_extension} 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}

    \cfunction{void}{PL_register_extensions}{PL_extension *e}
The function PL_register_extensions() behaves as PL_load_extensions(),
but is the only PL_* function that may be called \strong{before}
PL_initialise(). The predicates are registered {\bf into the module
\const{user}} after registration of the SWI-Prolog builtin foreign
predicates and before loading the initial saved state. This implies that
initialization/1 directives can refer to them.

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(predicates);

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

  ...
}
\end{code}
\end{description}


\subsection{Foreign Code Hooks}

For various specific applications some hooks re 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 toplevel 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}{void (*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 on your operating system) and the
\arg{closure} argument passed to the PL_on_halt() call.  See also
at_halt/1.
    \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}

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

\begin{itemlist}
    \item[Natural Prolog data]
E.i.\ using the representation one would choose if there was no foreign
interface required.
    \item[Opaque packed Prolog data]
Data can also be represetented in a foreign structure and stored on the
Prolog stacks using PL_put_string_nchars() and retrieved using
PL_get_string_chars().  It is generally good practice to wrap the
string in a compound term with arity 1, so Prolog can identify the
type.  portray/1 rules may be used to streamline printing such terms
during development.
    \item[Natural foreign data, passing a pointer]
An alternative is to pass a pointer to the foreign data. Again, this
functor may be wrapped in a compound term.
\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 of which Prolog never examines the contents
of the data itself. If the data is opaque to Prolog, the choosen
representation does not depend on simple analysis by Prolog, and the
selection will be driven solely by simplicity of the interface and
performance (both in time and space).
    \item[How big is the data]
Is effient encoding required?  For examine, a boolean aray may be
expressed as a compound term, holding integers each of which contains
a number of bits, or as a list of \const{true} and \const{false}.
    \item[What is the nature of the data]
For examples in C, constants are often expressed using `enum' or
\#define'd integer values. If prolog needs to handle this data, atoms
are a more logical choice.   Whether or not this mapping is used depends
on whether Prolog needs to interpret the data, how important debugging is
and how important performance is.
    \item[What is the lifetime of the data]
We can distinguish three cases.
    \begin{enumerate}
	\item
The lifetime is dictated by the accesibility of the data on the Prolog
stacks. Their is no way by which the foreign code when the data becomes
`garbage', and the data thus needs to be represented on the Prolog
stacks using Prolog data-types. (2),
        \item
The data lives on the `heap' and is explicitly allocated and
deallocated. In this case, representing the data using native foreign
representation and passing a pointer to it is a sensible choice.
	\item
The data lives as during the lifetime of a foreign predicate.  If the
predicate is deterministic, foreign automatic variables are suitable.
if the predicate is non-deterministic, the data may be allocated using
malloc() and a pointer may be passed.  See \secref{foreignnondet}.
    \end{enumerate}
\end{itemlist}


\subsubsection{Examples for storing foreign data}

In this section, we wull 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.  In the
second example, we look at handling a `netmask'.  Finally, we discuss
the outline of the DDE interface.

\paragraph{Integer sets} with not-to-far-apart upper- and lower-bounds
can be represented using bit-vectors. Common set operations, such as
union, intersection, etc. are reduced to simple and'ing and or'ing the
bitvectors. This can be done in Prolog, using a compound term holding
integer arguments. Especially if the integers are kept below the maximum
tagged integer value (see current_prolog_flag/2), this representation is
fairly space-efficient (wasting 1 word for the functor and and 7 bits
per integer for the tags). Arithmetic can all be performed in Prolog
too.

For really demanding applications, foreign representation will perform
better, especially time-wise. Bit-vectors are natrually expressed using
string objects. If the string is wrapped in \functor{bitvector}{1},
lower-bound of the vector is 0, and the upperbound is not defined, an
implementation for getting and putting the setes 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{Netmask's} are used with TCP/IP configuration. Suppose we
have an application dealing with reasoning about a network
configuration. Such an application requires communicating netmask
structures from the operating system, reasoning about them and possibly
communicate them to the user.  A netmask consists of 4 bitmasks between
0 and 255.  C-application normally see them as an 4-byte wide unsigned
integer.  SWI-Prolog cannot do that, as integers are always signed.

We could use the string approach outlined above, but this makes it
hard to handle these terms in Prolog.  A better choice is a compound
term netmask/4, holding the 4 submasks as integer arguments.

As the implementation is trivial, we will omit this here.

\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 aproach is to using PL_unify_pointer() and PL_get_pointer().
This approach is fast and easy, but has the drawbacks of (untyped)
pointers: there is no reliable way to detect the validity of the
pointer, not to verify it is pointing to a structure of the desired
type.  The pointer may be wrapped into a compound term with arity
1 (i.e., \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 a C-program}

As of version 2.1.0, SWI-Prolog may be embedded in a C-program.
To reach at a compiled C-program with SWI-Prolog as an embedded
application is very similar to creating a statically linked SWI-Prolog
executable as described in \secref{staticl}.

The file \file{\ldots/pl/include/stub.c} defines SWI-Prologs default main
program:


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

  PL_install_readline();        /* delete if you don't want readline */

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


This may be replaced with your own main C-program. The interface
function PL_initialise() {\bf must} be called before any of the other
SWI-Prolog foreign language functions described in this chapter.  
PL_initialise() interprets all the command-line arguments, except for
the \argoption{-t}{toplevel} flag that is interpreted by PL_toplevel().

\begin{description}
\cfunction{int}{PL_initialise}{int argc, char **argv}
Initialises the SWI-Prolog heap and stacks, restores the boot QLF file,
loads the system and personal initialisation files, runs the
at_initialization/1 hooks and finally runs the \argoption{-g}{goal}
hook.

Special consideration is required for \verb$argv[0]$. On {\bf Unix},
this argument passes the part of the commandline 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{libpl.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$"libpl.dll"$ as \verb$argv[0]$.

    \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{void}{PL_install_readline}{}
Installs the GNU-readline line-editor.  Embedded applications that do not
use the Prolog toplevel should normally delete this line, shrinking the
Prolog kernel significantly.

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

    \cfunction{void}{PL_cleanup}{int status}
This function performs the reverse of PL_initialise(). It runs the
PL_on_halt() and at_halt/1 handlers, closes all streams (except for the
`standard I/O' streams which are flushed only), deallocates all memory
and restores all signal handlers. The \arg{status} argument is passed to
the various termination hooks and indicates the \jargon{exit-status}.

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

    \cfunction{void}{PL_halt}{int status}
Cleanup the Prolog environment using PL_cleanup() and calls exit() with
the status argument.
\end{description}

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

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

In the normal usage, a copy is made of the default embedding template
\file{\ldots/pl/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 \funcref{GetModuleFileName}{}). The other elements of the
command-line may be modified. Next, \program{plld} is typically invoked
as:

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

\program{plld} 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: link.exe).
    \cmdlineoptionitem{-cc}{C-compiler}
Compiler for \fileext{c} files found on the commandline.  Default is the
compiler used to build SWI-Prolog (see current_prolog_flag/2) (Win32: cl.exe).
    \cmdlineoptionitem{-c++}{C++-compiler}
Compiler for C++ sources (extensions \fileext{cpp}, \fileext{cxx},
\fileext{cc} or \fileext{C}) files found on the commandline.  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{plld}.  In the latter case the state is created seperately and
appended to the kernel using \exam{cat <kernel> <state> > <out>}
(Win32: \exam{copy /b <kernel>+<state> <out>})
    \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} passed \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{-lpl}
(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{plld} 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{}{*}
I.e.\ all other options. These are passed as linker options to the
C-compiler.
\end{description}


\subsection{A simple 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 {calc}/1 predicate and calls
it.  The coder is in \figref{calc}.

\begin{figure}
\begin{code}
#include <stdio.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 following command-line:

\begin{code}
% plld -o calc calc.c calc.pl
\end{code}

\noindent
The following indicates the usage of the application:

\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 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 lower case 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 <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/pl-\plversion/include -fpic -c lowercase.c
% gcc -shared -o lowercase.so lowercase.o
% pl
Welcome to SWI-Prolog (Version \plversion)
Copyright (c) 1993-1996 University of Amsterdam.  All rights reserved.

For help, use ?- help(Topic). or ?- apropos(Word).

1 ?- load_foreign_library(lowercase).

Yes
2 ?- lowercase('Hello World!', L).

L = 'hello world!' 

Yes
\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{Memory Allocation}

SWI-Prolog's memory allocation is based on the \manref{malloc}{3}
library routines. Foreign applications can safely use
\manref{malloc}{3}, \manref{realloc}{3} and \manref{free}{3}. Memory
allocation using \manref{brk}{2} or \manref{sbrk}{2} is not allowed as
these calls conflict with \manref{malloc}{3}.

\subsection{Debugging Foreign Code}

Statically linked foreign code or embedded systems can be debugged
normally. Most modern environments provide debugging tools for
dynamically loaded shared objects or dynamic load libraries. The
following example traces the code of lowercase using \manref{gdb}{1} in
a Unix environment.

\begin{code}
% gcc -I/usr/local/lib/pl-2.2.0/include -fpic -c -g lowercase.c
% gcc -shared -o lowercase.so lowercase.o
% gdb pl
(gdb) r
Welcome to SWI-Prolog (Version \plversion)
Copyright (c) 1993-1996 University of Amsterdam.  All rights reserved.

For help, use ?- help(Topic). or ?- apropos(Word).

?- load_foreign_library(lowercase).
<type Control-C>
(gdb) shared                    % loads symbols for shared objects
(gdb) break pl_lowercase
(gdb) continue
?- lowercase('HELLO', X).
\end{code}

\subsection{Name Conflicts in C modules}

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 to 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}

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 uses <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.