- Documentation
- Reference manual
- Foreign Language Interface
- The Foreign Include File
- Argument Passing and Control
- Atoms and functors
- Analysing Terms via the Foreign Interface
- Constructing Terms
- Unifying data
- Convenient functions to generate Prolog exceptions
- Serializing and deserializing Prolog terms
- BLOBS: Using atoms to store arbitrary binary data
- Exchanging GMP numbers
- Calling Prolog from C
- Discarding Data
- String buffering
- Foreign Code and Modules
- Prolog exceptions in foreign code
- Catching Signals (Software Interrupts)
- Miscellaneous
- Errors and warnings
- Environment Control from Foreign Code
- Querying Prolog
- Registering Foreign Predicates
- Foreign Code Hooks
- Storing foreign data
- Embedding SWI-Prolog in other applications
- The Foreign Include File
- Foreign Language Interface
- Packages
- Reference manual
BUF_STACK
(default) or
BUF_MALLOC
. Strings returned by a function accepting
BUF_MALLOC
must be freed using PL_free().
Strings returned using BUF_STACK
are pushed on a stack that
is cleared when a foreign predicate returns control back to Prolog. More
fine grained control may be needed if functions that return strings are
called outside the context of a foreign predicate or a foreign predicate
creates many strings during its execution. Temporary strings are scoped
using these macros:
- void PL_STRINGS_MARK()
- void PL_STRINGS_RELEASE()
- These macros must be paired and create a C block ({...}). Any
string created using
BUF_STACK
after PL_STRINGS_MARK() is released by the corresponding PL_STRINGS_RELEASE(). These macros should be used like below... PL_STRINGS_MARK(); <operations involving strings> PL_STRINGS_RELEASE(); ...
The Prolog flag string_stack_tripwire may be used to set a tripwire to help finding places where scoping strings may help reducing resources.
12.4.14 Foreign Code and Modules
Modules are identified via a unique handle. The following functions are available to query and manipulate modules.
- module_t PL_context()
- Return the module identifier of the context module of the currently
active foreign predicate. If there is no currently active predicate it
returns a handle to the
user
module. - int PL_strip_module(term_t +raw, module_t *m, term_t -plain)
- Utility function. If raw is a term, possibly holding the
module construct <module>
:
<rest>, this function will make plain a reference to <rest> and fill module * with <module>. For further nested module constructs the innermost module is returned via module *. If raw is not a module construct, raw will simply be put in plain. The value pointed to by m must be initialized before calling PL_strip_module(), either to the default module or toNULL
. ANULL
value is replaced by the current context module if raw carries no module. The following example shows how to obtain the plain term and module if the default module is the user module:{ module m = PL_new_module(PL_new_atom("user")); term_t plain = PL_new_term_ref(); PL_strip_module(term, &m, plain); ... }
- atom_t PL_module_name(module_t module)
- Return the name of module as an atom.
- module_t PL_new_module(atom_t name)
- Find an existing module or create a new module with the name name.
Currently aborts the process with a fatal error on failure.
Future versions may raise a resource exception and return
(module_t)0
.
12.4.15 Prolog exceptions in foreign code
This section discusses PL_exception()
and PL_raise_exception(),
the interface functions to detect and generate Prolog exceptions from C
code. PL_raise_exception()
from the C interface registers the exception term and returns FALSE
.
If a foreign predicate returns
FALSE
, while an exception term is registered, a Prolog
exception will be raised by the virtual machine. This implies for a
foreign function that implements a predicate and wishes to raise an
exception, the function shall call PL_raise_exception(),
perform any necessary cleanup and return the return code of PL_raise_exception()
or explicitly
FALSE
. Calling PL_raise_exception()
outside the context of a function implementing a foreign predicate
results in undefined behaviour.
Note that many of the C API functions may call PL_raise_exception()
and return FALSE
. The user shall test for this, cleanup and
make the foreign function return FALSE
.
PL_exception()
may be used to inspect the currently registered exception. It is
normally called after a call to PL_next_solution()
returns FALSE
, and returns a term reference to an exception
term if an exception is pending, and (term_t)0
otherwise.
It may also be called after, e.g.,