- int PL_compare(term_t
t1, term_t t2)
- Compares two terms using the standard order of terms and returns -1, 0
or 1. See also compare/3.
- int PL_same_compound(term_t
t1, term_t t2)
- Yields
TRUE if t1 and t2 refer to
physically the same compound term and FALSE otherwise.
In some applications it is useful to store and retrieve Prolog terms
from C code. For example, the XPCE graphical environment does this for
storing arbitrary Prolog data as slot-data of XPCE objects.
Please note that the returned handles have no meaning at the Prolog
level and the recorded terms are not visible from Prolog. The functions
PL_recorded()
and PL_erase()
are the only functions that can operate on the stored term.
Two groups of functions are provided. The first group (PL_record()
and friends) store Prolog terms on the Prolog heap for retrieval during
the same session. These functions are also used by recorda/3
and friends. The recorded database may be used to communicate Prolog
terms between threads.
- record_t PL_record(term_t
+t)
- Record the term t into the Prolog database as recorda/3
and return an opaque handle to the term. The returned handle remains
valid until PL_erase()
is called on it. PL_recorded()
is used to copy recorded terms back to the Prolog stack.
- record_t PL_duplicate_record(record_t
record)
- Return a duplicate of record. As records are read-only
objects this function merely increments the records reference count.
- int PL_recorded(record_t
record, term_t -t)
- Copy a recorded term back to the Prolog stack. The same record may be
used to copy multiple instances at any time to the Prolog stack. Returns
TRUE
on success, and FALSE if there is not enough space on the
stack to accommodate the term. See also PL_record()
and PL_erase().
- void PL_erase(record_t
record)
- Remove the recorded term from the Prolog database, reclaiming all
associated memory resources.
The second group (headed by PL_record_external())
provides the same functionality, but the returned data has properties
that enable storing the data on an external device. It has been designed
to make it possible to store Prolog terms fast and compact in an
external database. Here are the main features:
- Independent of session
Records can be communicated to another Prolog session and made visible
using PL_recorded_external().
- Binary
The representation is binary for maximum performance. The returned data
may contain zero bytes.
- Byte-order independent
The representation can be transferred between machines with different
byte order.
- No alignment restrictions
There are no memory alignment restrictions and copies of the record can
thus be moved freely. For example, it is possible to use this
representation to exchange terms using shared memory between different
Prolog processes.
- Compact
It is assumed that a smaller memory footprint will eventually outperform
slightly faster representations.
- Stable
The format is designed for future enhancements without breaking
compatibility with older records.
- char * PL_record_external(term_t
+t, size_t *len)
- Record the term t into the Prolog database as recorda/3
and return an opaque handle to the term. The returned handle remains
valid until PL_erase_external()
is called on it.
It is allowed to copy the data and use PL_recorded_external()
on the copy. The user is responsible for the memory management of the
copy. After copying, the original may be discarded using
PL_erase_external().
PL_recorded_external()
is used to copy such recorded terms back to the Prolog stack.
- int PL_recorded_external(const
char *record, term_t -t)
- Copy a recorded term back to the Prolog stack. The same record may be
used to copy multiple instances at any time to the Prolog stack. See
also PL_record_external()
and PL_erase_external().
- int PL_erase_external(char
*record)
- Remove the recorded term from the Prolog database, reclaiming all
associated memory resources.
The function PL_get_file_name()
provides access to Prolog filenames and its file-search mechanism
described with absolute_file_name/3.
Its existence is motivated to realise a uniform interface to deal with
file properties, search, naming conventions, etc., from foreign code.
- int PL_get_file_name(term_t
spec, char **name, int flags)
- Translate a Prolog term into a file name. The name is stored in the
static buffer ring described with th PL_get_chars()
option
BUF_RING. Conversion from the internal UNICODE encoding is
done using standard C library functions. flags is a bit-mask
controlling the conversion process. Options are:
PL_FILE_ABSOLUTE- Return an absolute path to the requested file.
PL_FILE_OSPATH- Return the name using the hosting OS conventions. On MS-Windows,
\/
PL_FILE_SEARCH- Invoke absolute_file_name/3.
This implies rules from file_search_path/2
are used.
PL_FILE_EXIST- Demand the path to refer to an existing entity.
PL_FILE_READ- Demand read-access on the result.
PL_FILE_WRITE- Demand write-access on the result.
PL_FILE_EXECUTE- Demand execute-access on the result.
PL_FILE_NOERRORS- Do not raise any exceptions.
- int PL_get_file_nameW(term_t
spec, wchar_t **name, int flags)
- Same as PL_get_file_name(),
but returns the filename as a wide-character string. This is intended
for Windows to access the Unicode version of the Win32 API. Note that
the flag
PL_FILE_OSPATH must be provided to fetch a
filename in OS native (e.g., C:\x\y) notation.
Foreign code can set or create Prolog flags using PL_set_prolog_flag().
See set_prolog_flag/2
and create_prolog_flag/3.
To retrieve the value of a flag you can use PL_current_prolog_flag().
- int PL_set_prolog_flag(const
char *name, int type, ...)
- Set/create a Prolog flag from C. name is the name of the
affected flag. type is one of the values below, which also
dictates the type of the final argument. The function returns
TRUE on success and FALSE on failure. This
function can be called before PL_initialise(),
making the flag available to the Prolog startup code.
PL_BOOL- Create a boolean (
true or false) flag. The
argument must be an int.
PL_ATOM- Create a flag with an atom as value. The argument must be of type
const char *.
PL_INTEGER- Create a flag with an integer as value. The argument must be of type
intptr_t *.
- int PL_current_prolog_flag(atom_t
name, int type, void *value)
- Retrieve the value of a Prolog flag from C. name is the name
of the flag as an
atom_t (see current_prolog_flag/2).
type specifies the kind of value to be retrieved, it is one
of the values below. value is a pointer to a location where
to store the value. The user is responsible for making sure this memory
location is of the appropiate size/type (see the returned types below to
determine the size/type). The function returns TRUE on
success and FALSE on failure.
PL_ATOM- Retrieve a flag whose value is an
atom. The returned value
is an atom handle of type atom_t.
PL_INTEGER- Retrieve a flag whose value is an
integer. The returned
value is an integer of type int64_t.
PL_FLOAT- Retrieve a flag whose value is a
float. The returned value
is a floating point number of type double.
PL_TERM- Retrieve a flag whose value is a
term. The returned value
is a term handle of type term_t.