Prolog Compilers and Interpreters

Availability

XPCE runs on most Unix® platforms, Windows 95/98/ME, Windows NT/2000/XP and MacOS X (using X11). In the past, versions for Quintus- and SICStus Prolog as well as some Lisp dialects have existed. After discontinuing active Lisp development at SWI the Lisp versions have died. Active development on the Quintus and SICStus versions has been stopped due to lack of standardisation in the Prolog community. If adequate standards emerge we are happy to actively support other Prolog implementations.

Overview of the Interface

A special include file called 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 include in the SWI-Prolog home directory (?- 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:

1. Analysing Prolog terms
2. Constructing new terms
3. Unifying terms
4. Returning control information to Prolog
5. Registering foreign predicates with Prolog
6. Calling Prolog from C
7. Recorded database interactions
8. Global actions on Prolog (halt, break, abort, etc.)

Linking Foreign Modules

Foreign modules may be linked to Prolog in two ways. Using static linking, the extensions, a (short) file defining main() which attaches the extensions calls Prolog and the SWI-Prolog kernel distributed as a C-library are linked together to form a new executable. Using dynamic linking, the extensions are linked to a shared library (.so file on most Unix systems) or dynamic-link library (.DLL file on Microsoft platforms) and loaded into the running Prolog process.77.

What linking is provided?

The 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 open_shared_object (see current_prolog_flag/2). If this Prolog flag yields true, open_shared_object/2 and related predicates are defined. See here for a suitable high-level interface to these predicates.

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

Dynamic Linking of shared libraries

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

open_shared_object(+File, -Handle)

File is the name of a shared object file (called dynamic load library in MS-Windows). This file is attached to the current process and Handle is unified with a handle to the library. Equivalent to open_shared_object(File, [], Handle). See also load_foreign_library/[1,2].

On errors, an exception shared_object(Action, Message) is raised. Message is the return value from dlerror().

open_shared_object(+File, -Handle, +Options)

As open_shared_object/2, but allows for additional flags to be passed. Options is a list of atoms. now implies the symbols are resolved immediately rather than lazy (default). 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.

close_shared_object(+Handle)

Detach the shared object identified by Handle.

call_shared_object_function(+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().

Using the library shlib for .DLL and .so files

This section discusses the functionality of the (autoload) library shlib.pl, providing an interface to shared libraries. This library can only be used if the Prolog flag open_shared_object is enabled.

load_foreign_library(+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 foreign, which refers to the directories <plhome>/lib/<arch> and <plhome>/lib, in this order.

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

The Entry function will normally call PL_register_foreign() to declare functions in the library as foreign predicates.

load_foreign_library(+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 [n]or extension. It will then try the entry-point install-<base>. On failure it will try to function install(). Otherwise no install function will be called.

unload_foreign_library(+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.

current_foreign_library(-Lib, -Predicates)

Query the currently loaded foreign libraries and their predicates. Predicates is a list with elements of the form Module:Head, indicating the predicates installed with PL_register_foreign() when the entry-point of the library was called.

The following program connects a Windows message-box using a foreign function. This example was tested using Windows NT and Microsoft Visual C++ 2.0.

#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);
}

Static Linking

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

.../pl/runtime/<arch>/libpl.a 	SWI-Library
.../pl/include/SWI-Prolog.h 	Include file
.../pl/include/SWI-Stream.h 	Stream I/O include file
.../pl/include/SWI-Exports 	Export declarations (AIX only)
.../pl/include/stub.c 	Extension stub

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 .../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:

#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);
}

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 plld utility described elsewhere. If the linking is performed by hand, the command-line option -dump-runtime-variables can be used to obtain the required paths, libraries and linking options to link the new executable.

Interface Data types

Type term_t: a reference to a Prolog term

The principal data-type is term_t. Type term_t is what Quintus calls QP_term_ref. This name indicates better what the type represents: it is a 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 read, unify or write to term-references. In the this document we use the following notation for arguments of type term_t:

term_t +t

Accessed in read-mode. The '+' indicates the argument is 'input'.

term_t -t

Accessed in write-mode.

term_t ?t

Accessed in unify-mode.

Term references are obtained in any of the following ways:

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.

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.

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

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.

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

term_t PL_new_term_ref()

Return a fresh reference to a term. The reference is allocated on the 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.

term_t PL_new_term_refs(int n)

Return n new term references. The first term-reference is returned. The others are t+1, 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 very time-critical code requiring a number of term-references can be written as:

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

      ...
    }

term_t PL_copy_term_ref(term_t from)

Create a new term reference and make it point initially to the same term as from. This function is commonly used to copy a predicate argument to a term reference that may be written.

void PL_reset_term_refs(term_t after)

Destroy all term references that have been created after after, including 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().

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 (term_t), Prolog has all information necessary to perform its memory management without special precautions from the C-programmer.

Other foreign interface types

atom_t

An atom in Prolog's internal representation. Atoms are pointers to an opaque structure. They are a unique representation for represented text, which implies that atom A represents the same text as atom B if-and-only-if A and B are the same pointer.

Atoms are the central representation for textual constants in Prolog The transformation of 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.

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.

predicate_t

Handle to a Prolog predicate. Predicate handles live forever (although they can loose their definition).

qid_t

Query Identifier. Used by PL_open_query()/PL_next_solution()/PL_close_query() to handle backtracking from C.

fid_t

Frame Identifier. Used by PL_open_foreign_frame()/PL_close_foreign_frame().

module_t

A module is a unique handle to a Prolog module. Modules are used only to call predicates in a specific module.

foreign_t

Return type for a C-function implementing a Prolog predicate.

control_t

Passed as additional argument to non-deterministic foreign functions. See PL_retry*() and PL_foreign_context*().

install_t

Type for the install() and uninstall() functions of shared or dynamic link libraries.

int64_t

Actually part of the C99 standard rather than Prolog. As of version 5.5.6, Prolog integers are 64-bit on all hardware. The C99 type int64_t is defined in the stdint.h standard header and provides platform independent 64-bit integers. Portable code accessing Prolog should use this type to exchange integer values. Please note that PL_get_long() can return FALSE on Prolog integers outside the long domain. Robust code should not assume any of the integer fetching functions to succeed if the Prolog term is know to be an integer.

The Foreign Include File

Argument Passing and Control

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

(return) foreign_t PL_succeed()

Succeed deterministically. PL_succeed is defined as return TRUE.

(return) foreign_t PL_fail()

Fail and start Prolog backtracking. PL_fail is defined as return FALSE.

Non-deterministic Foreign Predicates

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

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

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

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

Initial call (PL_FIRST_CALL)

Prolog has just created a frame for the foreign function and asks it to produce the first answer.

Redo call (PL_REDO)

The previous invocation of the foreign function associated with the current goal indicated it was possible to backtrack. The foreign function should produce the next solution.

Terminate call (PL_CUTTED)

The choice point left by the foreign function has been destroyed by a cut. The foreign function is given the opportunity to clean the environment.

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

(return) foreign_t PL_retry(long)

The foreign function succeeds while leaving a choice point. On backtracking over this goal the foreign function will be called again, but the control argument now indicates it is a Redo call and the macro PL_foreign_context() returns the handle passed via PL_retry(). This handle is a 30 bits signed value (two bits are used for status indication). Defined as return_PL_retry(n). See also PL_succeed().

(return) foreign_t PL_retry_address(void *)

As PL_retry(), but ensures an address as returned by malloc() is correctly recovered by PL_foreign_context_address(). Defined as return_PL_retry_address(n). See also PL_succeed().

int PL_foreign_control(control_t)

Extracts the type of call from the control argument. The return values are described above. Note that the function should be prepared to handle the PL_CUTTED case and should be aware that the other arguments are not valid in this case.

long PL_foreign_context(control_t)

Extracts the context from the context argument. In the call type is PL_FIRST_CALL the context value is 0L. Otherwise it is the value returned by the last PL_retry() associated with this goal (both if the call type is PL_REDO as PL_CUTTED).

void * PL_foreign_context_address(control_t)

Extracts an address as passed in by PL_retry_address().

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

The following code shows a skeleton for a non-deterministic foreign predicate definition:

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

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

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

Atoms and functors

The following functions provide for communication using atoms and functors:

atom_t PL_new_atom(const char *)

Return an atom handle for the given C-string. This function always succeeds. The returned handle is valid as long as the atom is referenced.

const char* PL_atom_chars(atom_t atom)

Return a C-string for the text represented by the given atom. The returned text will not be changed by Prolog. It is not allowed to modify the contents, not even temporary as the string may reside in read-only memory. The returned string becomes invalid if the atom is garbage-collected (see section Atoms and atom-garbage collection). Foreign functions that require the text from an atom passed in a term_t normally use PL_get_atom_chars() or PL_get_atom_nchars().

functor_t PL_new_functor(atom_t name, int arity)

Returns a functor identifier, a handle for the name/arity pair. The returned handle is valid for the entire Prolog session.

atom_t PL_functor_name(functor_t f)

Return an atom representing the name of the given functor.

int PL_functor_arity(functor_t f)

Return the arity of the given functor.

Atoms and atom-garbage collection

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

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

void PL_register_atom(atom_t atom)

Increment the reference count of the atom by one. PL_new_atom() performs this automatically, returning an atom with a reference count of at least one.

void PL_unregister_atom(atom_t atom)

Decrement the reference count of the atom. If the reference-count drops below zero, an assertion error is raised.

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

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

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

Analysing Terms via the Foreign Interface

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

Testing the type of a term

int PL_term_type(term_t)

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

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

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

or

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

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

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

int PL_is_variable(term_t)

Returns non-zero if term is a variable.

int PL_is_ground(term_t)

Returns non-zero if term is a ground term. See also ground/1. This function is cycle-safe.

int PL_is_atom(term_t)

Returns non-zero if term is an atom.

int PL_is_string(term_t)

Returns non-zero if term is a string.

int PL_is_integer(term_t)

Returns non-zero if term is an integer.

int PL_is_float(term_t)

Returns non-zero if term is a float.

int PL_is_compound(term_t)

Returns non-zero if term is a compound term.

int PL_is_functor(term_t, functor_t)

Returns non-zero if term is compound and its functor is functor. This test is equivalent to PL_get_functor(), followed by testing the functor, but easier to write and faster.

int PL_is_list(term_t)

Returns non-zero if term is a compound term with functor ./2 or the atom [].

int PL_is_atomic(term_t)

Returns non-zero if term is atomic (not variable or compound).

int PL_is_number(term_t)

Returns non-zero if term is an integer or float.

int PL_is_acyclic(term_t)

Returns non-zero if term is acyclic (i.e. a finite tree).

Reading data from a term

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

int PL_get_atom(term_t +t, atom_t *a)

If t is an atom, store the unique atom identifier over a. See also PL_atom_chars() and PL_new_atom(). If there is no need to access the data (characters) of an atom, it is advised to manipulate atoms using their handle. As the atom is referenced by t, it will live at least as long as t does. If longer life-time is required, the atom should be locked using PL_register_atom().

int PL_get_atom_chars(term_t +t, char **s)

If t is an atom, store a pointer to a 0-terminated C-string in s. It is explicitly not allowed to modify the contents of this string. Some built-in atoms may have the string allocated in read-only memory, so temporary manipulation can cause an error.

int PL_get_string_chars(term_t +t, char **s, int *len)

If t is a string object, store a pointer to a 0-terminated C-string in s and the length of the string in len. Note that this pointer is invalidated by backtracking, garbage-collection and stack-shifts, so generally the only safe operations are to pass it immediately to a C-function that doesn't involve Prolog.

int PL_get_chars(term_t +t, char **s, unsigned flags)

Convert the argument term t to a 0-terminated C-string. flags is a bitwise disjunction from two groups of constants. The first specifies which term-types should converted and the second how the argument is stored. Below is a specification of these constants. BUF_RING implies, if the data is not static (as from an atom), the data is copied to the next buffer from a ring of 16 buffers. This is a convenient way of converting multiple arguments passed to a foreign predicate to C-strings. If BUF_MALLOC is used, the data must be freed using PL_free() when not needed any longer.

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

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

int PL_get_list_chars(+term_t l, char **s, unsigned flags)

Same as PL_get_chars(l, s, CVT_LIST|flags), provided flags contains none of the CVT_* flags.

int PL_get_integer(+term_t t, int *i)

If t is a Prolog integer, assign its value over i. On 32-bit machines, this is the same as PL_get_long(), but avoids a warning from the compiler. See also PL_get_long().

int PL_get_long(term_t +t, long *i)

If t is a Prolog integer that can be represented as a long, assign its value over i. If t is an integer that cannot be represented by a C long, this function returns FALSE. If t is a floating point number that can be represented as a long, this function succeeds as well. See also PL_get_int64()

int PL_get_int64(term_t +t, int64_t *i)

If t is a Prolog integer or float that can be represented as a int64_t, assign its value over i. Currently all Prolog integers can be represented using this type, but this might change if SWI-Prolog introduces unbounded integers.

int PL_get_bool(term_t +t, int *val)

If t has the value true or false, set val to the C constant TRUE or FALSE and return success. otherwise return failure.

int PL_get_pointer(term_t +t, void **ptr)

In the current system, pointers are represented by Prolog integers, but need some manipulation to make sure they do not get truncated due to the limited Prolog integer range. PL_put_pointer() amd PL_get_pointer() guarantee pointers in the range of malloc() are handled without truncating.

int PL_get_float(term_t +t, double *f)

If t is a float or integer, its value is assigned over f.

int PL_get_functor(term_t +t, functor_t *f)

If t is compound or an atom, the Prolog representation of the name-arity pair will be assigned over f. See also PL_get_name_arity() and PL_is_functor().

int PL_get_name_arity(term_t +t, atom_t *name, int *arity)

If t is compound or an atom, the functor-name will be assigned over name and the arity over arity. See also PL_get_functor() and PL_is_functor().

int PL_get_module(term_t +t, module_t *module)

If t is an atom, the system will lookup or create the corresponding module and assign an opaque pointer to it over module.

int PL_get_arg(int index, term_t +t, term_t -a)

If t is compound and index is between 1 and arity (including), assign a with a term-reference to the argument.

int _PL_get_arg(int index, term_t +t, term_t -a)

Same as PL_get_arg(), but no checking is performed, nor whether t is actually a term, nor whether index is a valid argument-index.

Exchanging text using length and string

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

PL_get_atom_nchars(term_t t, size_t *len, char **s)

See PL_get_atom_chars().

int PL_get_list_nchars(term_t t, size_t *len, char **s)

See PL_get_list_chars().

int PL_get_nchars(term_t t, size_t *len, char **s, unsigned int flags)

See PL_get_chars().

int PL_put_atom_nchars(term_t t, size_t len, const char *s)

See PL_put_atom_chars().

int PL_put_string_nchars(term_t t, size_t len, const char *s)

See PL_put_string_chars().

int PL_put_list_ncodes(term_t t, size_t len, const char *s)

See PL_put_list_codes().

int PL_put_list_nchars(term_t t, size_t len, const char *s)

See PL_put_list_chars().

int PL_unify_atom_nchars(term_t t, size_t len, const char *s)

See PL_unify_atom_chars().

int PL_unify_string_nchars(term_t t, size_t len, const char *s)

See PL_unify_string_chars().

int PL_unify_list_ncodes(term_t t, size_t len, const char *s)

See PL_unify_codes().

int PL_unify_list_nchars(term_t t, size_t len, const char *s)

See PL_unify_list_chars().

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

atom_t PL_new_atom_nchars(size_t len, const char *s)

Create a new atom as PL_new_atom(), but from length len and characters s.

const char * PL_atom_nchars(atom_t a, size_t *len)

Extract text and length of an atom.

Wide character versions

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

atom_t PL_new_atom_wchars(size_t len, const pl_wchar_t *s)

Create atom from wide-character string as PL_new_atom_nchars() does for ISO-Latin-1 strings. If s only contains ISO-Latin-1 characters a normal byte-array atom is created.

pl_wchar_t* PL_atom_wchars(atom_t atom, int *len)

Extract characters from a wide-character atom. Fails (returns NULL) if atom is not a wide-character atom. This is the wide-character version of PL_atom_nchars(). Note that only one of these functions succeeds on a particular atom. Especially, after creating an atom with PL_new_atom_wchars(), extracting the text using PL_atom_wchars() will fail if the atom only contains ISO-Latin-1 characters.

int PL_get_wchars(term_t t, size_t *len, pl_wchar_t **s, unsigned flags)

Wide-character version of PL_get_chars(). The flags argument is the same as for PL_get_chars().

int PL_unify_wchars(term_t t, int type, size_t len, const pl_wchar_t *s)

Unify t with a textual representation of the C wide character array s. The argtype argument defines the Prolog representation and is one of PL_ATOM, PL_STRING, PL_CODE_LIST or PL_CHAR_LIST.

int PL_unify_wchars_diff(term_t +t, term_t -tail, int type, size_t len, const pl_wchar_t *s)

Difference list version of PL_unify_wchars(), only supporting the types PL_CODE_LIST and PL_CHAR_LIST. It serves two purposes. It allows for returning very long lists from data read from a stream without the need for a resizing buffer in C. Also, the use of difference lists is often practical for further processing in Prolog. Examples can be found in packages/clib/readutil.c from the source distribution.

Reading a list

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

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

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

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

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

PL_get_list(term_t +l, term_t -h, term_t -t)

If l is a list and not [] assign a term-reference to the head to h and to the tail to t.

PL_get_head(term_t +l, term_t -h)

If l is a list and not [] assign a term-reference to the head to h.

PL_get_tail(term_t +l, term_t -t)

If l is a list and not [] assign a term-reference to the tail to t.

PL_get_nil(term_t +l)

Succeeds if represents the atom [].

An example: defining write/1 in C

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

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

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

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

  PL_succeed;
}

Constructing Terms

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

void PL_put_variable(term_t -t)

Put a fresh variable in the term. The new variable lives on the global stack. Note that the initial variable lives on the local stack and is lost after a write to the term-references. After using this function, the variable will continue to live.

void PL_put_atom(term_t -t, atom_t a)

Put an atom in the term reference from a handle. See also PL_new_atom() and PL_atom_chars().

void PL_put_atom_chars(term_t -t, const char *chars)

Put an atom in the term-reference constructed from the 0-terminated string. The string itself will never be referenced by Prolog after this function.

void PL_put_string_chars(term_t -t, const char *chars)

Put a zero-terminated string in the term-reference. The data will be copied. See also PL_put_string_nchars().

void PL_put_string_nchars(term_t -t, size_t len, const char *chars)

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

void PL_put_list_chars(term_t -t, const char *chars)

Put a list of ASCII values in the term-reference.

void PL_put_integer(term_t -t, long i)

Put a Prolog integer in the term reference.

void PL_put_int64(term_t -t, int64_t i)

Put a Prolog integer in the term reference t.

void PL_put_pointer(term_t -t, void *ptr)

Put a Prolog integer in the term-reference. Provided ptr is in the `malloc()-area', PL_get_pointer() will get the pointer back.

void PL_put_float(term_t -t, double f)

Put a floating-point value in the term-reference.

void PL_put_functor(term_t -t, functor_t functor)

Create a new compound term from functor and bind t to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the PL_unify_*() functions or use PL_cons_functor().

void PL_put_list(term_t -l)

Same as PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2)).

void PL_put_nil(term_t -l)

Same as PL_put_atom_chars("[]").

void PL_put_term(term_t -t1, term_t +t2)

Make t1 point to the same term as t2.

void PL_cons_functor(term_t -h, functor_t f, ...)

Create a term, whose arguments are filled from variable argument list holding the same number of term_t objects as the arity of the functor. To create the term animal(gnu, 50), use:

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

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

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

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

void PL_cons_functor_v(term_t -h, functor_t f, term_t a0)

Creates a compound term like PL_cons_functor(), but a0 is an array of term references as returned by PL_new_term_refs(). The length of this array should match the number of arguments required by the functor.

void PL_cons_list(term_t -l, term_t +h, term_t +t)

Create a list (cons-) cell in l from the head and tail. The code below creates a list of atoms from a char **. The list is built tail-to-head. The PL_unify_*() functions can be used to build a list head-to-tail.

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

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

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

Unifying data

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

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

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

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

  PL_fail;
}

Using PL_unify_atom_chars(), this becomes:

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

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

  PL_fail;
}

int PL_unify(term_t ?t1, term_t ?t2)

Unify two Prolog terms and return non-zero on success.

int PL_unify_atom(term_t ?t, atom_t a)

Unify t with the atom a and return non-zero on success.

int PL_unify_chars(term_t ?t, int flags, size_t len, const char *chars)

New function to deal with unification of char* with various encodings to a Prolog representation. The flags argument is a bitwise or specifying the Prolog target type and the encoding of chars. Prolog types is one of PL_ATOM, PL_STRING, PL_CODE_LIST or PL_CHAR_LIST. Representations is one of REP_ISO_LATIN_1, REP_UTF8 or REP_MB. See PL_get_chars() for a definition of the representation types. If len is -1, then chars must be 0-terminated and the length is computed from chars using strlen().

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

int PL_unify_atom_chars(term_t ?t, const char *chars)

Unify t with an atom created from chars and return non-zero on success.

int PL_unify_list_chars(term_t ?t, const char *chars)

Unify t with a list of ASCII characters constructed from chars.

void PL_unify_string_chars(term_t ?t, const char *chars)

Unify t with a Prolog string object created from the zero-terminated string chars. The data will be copied. See also PL_unify_string_nchars().

void PL_unify_string_nchars(term_t ?t, size_t len, const char *chars)

Unify t with a Prolog string object created from the string created from the len/chars pair. The data will be copied. This interface can deal with 0-bytes in the string.

int PL_unify_integer(term_t ?t, long n)

Unify t with a Prolog integer from n.

int PL_unify_int64(term_t ?t, int64_t n)

Unify t with a Prolog integer from n.

int PL_unify_float(term_t ?t, double f)

Unify t with a Prolog float from f.

int PL_unify_pointer(term_t ?t, void *ptr)

Unify t with a Prolog integer describing the pointer. See also PL_put_pointer() and PL_get_pointer().

int PL_unify_functor(term_t ?t, functor_t f)

If t is a compound term with the given functor, just succeed. If it is unbound, create a term and bind the variable, else fails. Note that this function does not create a term if the argument is already instantiated.

int PL_unify_list(term_t ?l, term_t -h, term_t -t)

Unify l with a list-cell (./2). If successful, write a reference to the head of the list to h and a reference to the tail of the list into t. This reference may be used for subsequent calls to this function. Suppose we want to return a list of atoms from a char **. We could use the example described by PL_put_list(), followed by a call to PL_unify(), or we can use the code below. If the predicate argument is unbound, the difference is minimal (the code based on PL_put_list() is probably slightly faster). If the argument is bound, the code below may fail before reaching the end of the word-list, but even if the unification succeeds, this code avoids a duplicate (garbage) list and a deep unification.

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

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

                                      return PL_unify_nil(l);
                                    }

int PL_unify_nil(term_t ?l)

Unify l with the atom [].

int PL_unify_arg(int index, term_t ?t, term_t ?a)

Unifies the index-th argument (1-based) of t with a.

int PL_unify_term(term_t ?t, ...)

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

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

The type identifiers are:

PL_VARIABLE: none

No op. Used in arguments of PL_FUNCTOR.

PL_BOOL: int

Unify the argument with true or false.

PL_ATOM: atom_t

Unify the argument with an atom, as in PL_unify_atom().

PL_CHARS: const char *

Unify the argument with an atom, constructed from the C char *, as in PL_unify_atom_chars().

PL_NCHARS: size_t, const char *

Unify the argument with an atom, constructed from length and char* as in PL_unify_atom_nchars().

PL_UTF8_CHARS const char * Create an atom from a UTF-8 string. PL_UTF8_STRING const char * Create a packed string object from a UTF-8 string.

PL_MBCHARS: const char *

Create an atom from a multi-byte string in the current locale.

PL_MBCODES: const char *

Create a list of character codes from a multi-byte string in the current locale.

PL_MBSTRING: const char *

Create a packed string object from a multi-byte string in the current locale.

PL_NWCHARS: size_t, const wchar_t *

Create an atom from a length and a wide character pointer.

PL_NWCODES: size_t, const wchar_t *

Create an list of character codes from a length and a wide character pointer.

PL_NWSTRING: size_t, const wchar_t *

Create a packed string object from a length and a wide character pointer.

PL_SHORT: short

Unify the argument with an integer, as in PL_unify_integer(). As short is promoted to int, PL_SHORT is a synonym for PL_INT.

PL_INTEGER: long

Unify the argument with an integer, as in PL_unify_integer().

PL_INT: int

Unify the argument with an integer, as in PL_unify_integer().

PL_LONG: long

Unify the argument with an integer, as in PL_unify_integer().

PL_INT64: int64_t

Unify the argument with a 64-bit integer, as in PL_unify_int64().

PL_INTPTR: intptr_t

Unify the argument with an integer with the same width as a pointer. On most machines this is the same as PL_LONG. but on 64-bit MS-Windows pointers are 64-bit while longs are only 32-bits.

PL_DOUBLE: double

Unify the argument with a float, as in PL_unify_float(). Note that, as the argument is passed using the C vararg conventions, a float must be casted to a double explicitly.

PL_FLOAT: double

Unify the argument with a float, as in PL_unify_float().

PL_POINTER: void *

Unify the argument with a pointer, as in PL_unify_pointer().

PL_STRING: const char *

Unify the argument with a string object, as in PL_unify_string_chars().

PL_TERM: term_t

Unify a subterm. Note this may the return value of a PL_new_term_ref() call to get access to a variable.

PL_FUNCTOR: functor_t, ...

Unify the argument with a compound term. This specification should be followed by exactly as many specifications as the number of arguments of the compound term.

PL_FUNCTOR_CHARS: const char *name, int arity, ...

Create a functor from the given name and arity and then behave as PL_FUNCTOR.

PL_LIST: int length, ...

Create a list of the indicated length. The following arguments contain the elements of the list.

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

static functor_t FUNCTOR_language1;

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

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

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

int PL_chars_to_term(const char *chars, term_t -t)

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

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

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

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

      PL_discard_foreign_frame(fid);
      return rval;
    }

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

char * PL_quote(int chr, const char *string)

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

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

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

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

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

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

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

  mpz_clear(mpz);
  return rc;
}

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

int
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;
}

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

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

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

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

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

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

      return FALSE;
    }

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

#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);
}

GNU Prolog's Language Bindings*