Quintus Prolog Manual

(PREV) (NEXT)

m-1: Return Values and Errors

Quintus Prolog C functions return the following:

integer
one of
QP_SUCCESS
(0)
QP_FAILURE
(-1)
QP_ERROR
(-2)
boolean
true (1), false (0)
pointer
a pointer or null (0)

In some error situations, a global variable, QP_errno may also be set to give more information about the error condition. Those I/O related predicates which take a Prolog stream argument do not set the error code in QP_errno. Instead, they set the errno field of the stream. There are two QP_ functions provided to help diagnose error conditions from error numbers:

In addition, the error number is sometimes reported in the message field of exception terms, as in 



        existence_error(Goal, _,_,_,errno(<error number>))

See {manual(REFPAGE-CONV)} for a description of the conventions observed in the Reference Pages for Prolog predicates. 'C' function Reference Pages differ primarily in the synopsis.

m-2: Topical List of C Functions

Following is a complete list of Quintus-supplied C functions. They fall into two categories: built-in and user-redefinable. The user-redefinable functions are used in embedding Prolog sub-programs (see {manual(i-2)}). Quintus provides default definitions for these functions, and for most purposes it is unneccessary to even know about them. However, it is possible to redefine any of these to make Quintus Prolog programs behave appropriately when embedded in C code. Changi these default definitions means replacing them with your own code, not adding clauses. By convention these functions are named to be recognizable as C functions, and as belonging to one or the other of these categories: Regular C builtins are prefixed with QP_ and user-redefinable ones with QU_.

m-2-1: C Errors

A') mpg.c-chapter.html#mpg.c-builtinsC_Errors">') ')

m-2-2: Character I/O

A') mpg.c-chapter.html#mpg.c-builtinsCharacter_I/O">') ')

m-2-3: Exceptions

A') mpg.c-chapter.html#mpg.c-builtinsExceptions">') ')

m-2-4: Files and Streams

A') mpg.c-chapter.html#mpg.c-builtinsFiles_and_Streams">') ')

m-2-5: Foreign Interface

A') mpg.c-chapter.html#mpg.c-builtinsForeign_Interface">') ')

m-2-6: Input Services

A') mpg.c-chapter.html#mpg.c-builtinsInput_Services">') ')

m-2-7: main()

A') mpg.c-chapter.html#mpg.c-builtinsmain__">') ") ')

m-2-8: Memory Management

A') mpg.c-chapter.html#mpg.c-builtinsMemory_Management">') ')

m-2-9: Signal Handling

A') mpg.c-chapter.html#mpg.c-builtinsSignal_Handling">') ')

m-2-10: Terms in C

A') mpg.c-chapter.html#mpg.c-builtinsTerms_in_C">') ')

m-2-11: Term I/O

A') mpg.c-chapter.html#mpg.c-builtinsTerm_I/O">') ')

m-2-12: Type Tests

A') mpg.c-chapter.html#mpg.c-builtinsType_Tests">') ')

m-3: C Functions

m-3-0:

The following reference pages, alphabetically arranged, describe the Quintus Prolog built-in C functions. For a functional grouping of these functions including brief descriptions, see {manual(m-2)}. For information about return values and errors, see {manual(m-1)}

QP_action()

Synopsis:
#include <quintus/quintus.h> 
          int QP_action(action)

          
          int action;
Called to request certain actions of Prolog.
Arguments:
action is one of:
          QP_ABORT        *Abort to the current break level

          QP_REALLY_ABORT *Abort to top level

          QP_STOP          Stop (suspend) process

          QP_IGNORE        Do nothing

          QP_EXIT          Exit Prolog immediately

          QP_MENU          Present action menu

          QP_TRACE         Turn on trace mode

          QP_DEBUG         Turn on debugging

          QP_ARITH        *Print an arithmetic error and abort

                                     (obsolete)
Description:
Return Value:
QP_ERROR, QP_SUCCESS
Errors:
Examples:
For a full discussion of QP_action() and examples of its use, see {manual(g-11-2)}

QP_add_*()

Synopsis:
#include <quintus/quintus.h> 
          int QP_add_input(id,fn,data,flush_fn, flush_data)

          
          int  id;

             void (*fn)();

             char *data;

             void (*flush_fn)();

             char *flush_data;

          
          int QP_add_output(id,fn,data,flush_fn,flush_data)

          
          int  id;

             void (*fn)();

             char *data;

             void (*flush_fn)();

             char *flush_data;

          
          int QP_add_exception(id,fn,data,flush_fn,flush_data)

          
          int  id;

             void (*fn)();

             char *data;

             void (*flush_fn)();

             char *flush_data;

          
          int QP_add_timer(msecs,fn,data)

          
          int  msecs;

             void (*fn)();

             char *data;

          
          int QP_add_absolute_timer(timeo,fn,data)

          
          struct timeval *timeo;

             void (*fn)();

             char *data;
These C functions register callback functions to be called on input/output or timing events.
Description:
Return Values:
QP_add_timer() and QP_add_absolute_time() return a
timerid if successful. Other functions return QP_SUCCESS.
All functions return QP_ERROR if an error occurs.
Tips:
Often your code will maintain a buffer associated with an input connection. If this is the case, then your flush function must check for this buffered input, and as long as it finds some, it should repeatedly call your callback function directly. If you don't do this, then your callback function may not be called, even though you have pending input, since the operating system isn't aware of your buffer.
See Also:
QP_wait_input(), QP_select(), QP_remove_*()

QP_add_tty()

Synopsis:
#include <quintus/quintus.h> 
          int QP_add_tty(stream, tty_id)

          
          QP_stream *stream;

             char      *tty_id;
Register a created Prolog stream to a tty stream group.
Arguments:
stream
a pointer to a valid stream structure
tty_id
an identification string for a tty group
Description:
This function is used to register a stream to a tty group. All the streams in a tty group share a single stream position (see the reference pages for line_count/2, line_position/2 and character_count/2). When input is requested on one of the streams and the shared line position is 0, a prompt is output on one of the output streams.
See Also:
{manual(i-5-4)}

QP_atom_from_string(), QP_atom_from_padded_string()

Synopsis:
#include <quintus/quintus.h> 
          QP_atom QP_atom_from_string(string)

          
          char *string;
Returns the canonical representation of the atom whose printed representation is the (null-terminated) string string. 
          int

          QP_atom_from_padded_string(p_atom, p_string, p_length)

          
          QP_atom *p_atom;

             char    *p_string;

             int     *p_length;
Returns the canonical representation of the atom whose printed representation is the (blank-padded) string p_string in a character array of length p_length.
Description:
Examples:
rev_atom() is a C function that takes an atom and returns an atom whose string representation is the reverse of the string representation of the atom passed in.
IN THE PROLOG CODE:
          foreign(rev_atom, c, rev_atom(+atom, [-atom])).
IN THE C CODE:
QP_atom rev_atom(atom) QP_atom atom; { char *string[MAX_ATOM_LEN]; strcpy(string, QP_string_from_atom(atom)); reverse(string); /* reverses string in place */ return QP_atom_from_string(string); }
Giving:
| ?- rev_atom(draw, X). X = ward yes | ?-
See Also:
QP_string_from_atom(), QP_padded_string_from_atom()
{manual(i-3-7)}

QP_char_count()

Synopsis:
#include <quintus/quintus.h> 
          int QP_char_count(stream)

          
          QP_stream *stream;
Obtains the current character count for the Prolog stream stream. QP_char_count() is a macro.
Arguments:
stream
a pointer to a valid Prolog stream structure
See Also:
QP_get_pos(), QP_line_count(), QP_line_position(), character_count/2, QP_getpos(), QP_setpos(), QP_seek(), stream_position/[2,3]
{manual(i-5)}

QP_clearerr()

Synopsis:
#include <quintus/quintus.h> 
          void QP_clearerr(stream)

          
          QP_stream *stream;
Resets the error indication and EOF indication to zero on the named stream.
QP_clearerr() is similar to the UNIX C library function clearerr(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
{manual(i-5)}

QP_close_query()

Synopsis:
#include <quintus/quintus.h> 
          int QP_close_query(qid)

          
          QP_qid qid;
Equivalent to the Prolog call: 


                       !, fail.
Description:
Return Values:
QP_SUCCESS
Query was closed successfully
QP_ERROR
either the query could not be closed or an exception was signalled from Prolog but not caught
See Also:
QP_cut_query(), QP_open_query(), QP_query(), QP_next_solution(), QP_pred(), QP_predicate(), {manual(i-4)}

QP_compare()

Synopsis:
#include <quintus/quintus.h> 
          int QP_compare(term1, term2)

          
          QP_term_ref term1;

             QP_term_ref term2;
Compares the two terms referenced by term1 and term2. Both arguments are term1 before term2
Description:
The comparison uses the standard total ordering of Prolog terms (also used by the built-in Prolog predicate compare/3). 


          In Standard Order:         Ret Value

          term1 before term2              -1

          term1 = term2                    0

          term1 after term2                1
Examples:
c_compare(term1, term2) is an equivalent C version of the Prolog builtin compare/3:
foreign(c_compare, c, c_compare(+term, +term, +term)). #include <quintus/quintus.h> int c_compare(t1, t2, t3) QP_term_ref t1, t2; { int res; QP_term_ref l_than = QP_new_term_ref(); QP_term_ref equal = QP_new_term_ref(); QP_term_ref g_than = QP_new_term_ref(); QP_put_atom(l_than, QP_atom_from_string("<")); QP_put_atom(equal, QP_atom_from_string("=")); QP_put_atom(g_than, QP_atom_from_string(">")); res = QP_compare(t2, t3); if ( res < 0) { return QP_unify(t1, l_than); } else if (res == 0) { return QP_unify(t1, equal); } else if (res > 0) { return QP_unify(t1, g_than); } }
See Also::
QP_unify(), compare/3

QP_cons_*()

Synopsis:
#include <quintus/quintus.h> 
          void QP_cons_list(term, head, tail)

          
          QP_term_ref term;

             QP_term_ref head;

             QP_term_ref tail;

          
          void QP_cons_functor(term, name, arity,

                                  arg1, ... ,arg_arity)

          
          QP_term_ref   term;

             QP_atom       name;

             int           arity;

             QP_term_ref   arg1, ... , arg_arity;
Description:
Examples:
float_to_chars() is a C function that converts a floating point number to a list of characters. Note the use of QP_put_integer().
foreign(flt_to_chars, flt_to_chars(+float, -term)). #include <quintus/quintus.h> void flt_to_chars(flt, chars) float flt; QP_term_ref chars; { char buffer[28], *p; int len; QP_term_ref term_char = QP_new_term_ref(); QP_put_nil(chars); sprintf( buffer , "%.17e" , flt ); /* move to end of buffer */ for (p=buffer, len=0; *p; p++, len++); while ( len-- ) { QP_put_integer(term_char, *--p); QP_cons_list(chars, term_char, chars); } }
See Also::
QP_term_type(), QP_get_*(), QP_new_term_ref()

QP_cut_query()

Synopsis:
#include <quintus/quintus.h> 
          int QP_cut_query(qid)

          
          QP_qid qid;
Equivalent to just calling "!" in Prolog.
Description:
The computation is rendered determinate, but as it is not failed over the Prolog heap is not popped. Thus when terminating a query using QP_cut_query() more space may be retained, but so is the last solution.
Return Values:
QP_SUCCESS
QP_ERROR
either something is wrong with the QP_qid or Prolog has not been initialized
See Also:
QP_query(), QP_close_query(), QP_next_solution(), QP_open_query(), QP_pred(), QP_predicate()
{manual(i-4)}

QP_error_message()

Synopsis:
#include <quintus/quintus.h> 
          int QP_error_message(errno, is_qp_error, error_string)

          
          int    errno;

             int   *is_qp_error;

             char **error_string;
Arguments:
errno
the error number in question
is_qp_error
set to:
0
if it is not an error number created by Quintus.
1
if it is an error number created by Quintus.
error_string
the text of the error message.
Description:
This function supplies the text corresponding to the error number errno. The output parameter is_qp_error can be used to determine if the error number was one created by Quintus or is a UNIX error number.
Typically, the error number of interest is the one in the global variable QP_errno. This variable is discussed in the man pages for QP_perror().
Return Value:
QP_SUCCESS
Examples:
The following fragment takes the status value returned by some function that returns C calling Prolog style status values and prints out the corresponding error. 
          #include <quintus/quintus.h>

              ...

          int is_qp_error;

          char *error_message;

              ...

          status = some_function();

          switch(status) {

          case QP_ERROR:

              (void) QP_error_message(QP_errno, &is_qp_error,

                  &error_message);

              if(is_qp_error)

                  (void) QP_fputs("prolog error: ", QP_stderr);

              else (void) QP_fputs("UNIX error: ", QP_stderr);

              (void) QP_fputs(error_message, QP_stderr);

              (void) QP_fnewln(QP_stderr);

              ...
See Also:
QP_perror()

QP_exception_term()

Synopsis:
#include <quintus/quintus.h > 
          int QP_exception(term)

          
          QP_term_ref term;
A function that users can call when their call to Prolog signals an error. If QP_query() returns QP_ERROR then users can call QP_exception_term() to get at the exception term signalled.
Description:
If C calls Prolog and the Prolog goal raises an exception, QP_query() (or QP_next_solution()) returns the value QP_ERROR. If the user wants to get at the exception term that has been raised, they can call the function QP_exception_term(). QP_exception_term() takes a QP_term_ref as argument and returns a Prolog term.
Example:
IN THE PROLOG CODE:
          :- extern(error).



          error :- raise_exception(error_term(from_prolog)).
IN THE C CODE:
        QP_pred_ref pred;



        if ((pred = QP_predicate("error",0,"user")) !=

            (QP_pred_ref) QP_ERROR) {



            if (QP_query(pred) == QP_ERROR) {

                QP_term_ref err_term = QP_new_term_ref();



                QP_exception_term(err_term);

            }

        }
Once you get err_term, you can use functions such as the QP_get_*() family to take apart the error term or to print it.
See Also:
QP_query(), QP_next_solution(), raise_exception/3
{manual(g-19)}

QP_fclose()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fclose(stream)

          
          QP_stream *stream;
Writes out any buffered data for the named stream, and closes the named stream.
QP_fclose() is similar to the UNIX C library function fclose(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fopen()
{manual(i-5)}

QP_fdopen()

Synopsis:
#include <quintus/quintus.h> 
          QP_stream *QP_fdopen(fildes, type)

          
          int   fildes;

             char *type;
Associates a stream with the file descriptor files. File descriptors are obtained from calls like the UNIX open(2V), dup(2), creat(2), or pipe(2), which open files but do not return streams. Streams are necessary input for many of the UNIX Section 3S library routines. The type of the stream must agree with the mode of the open file.
QP_fdopen() is similar to the UNIX C library function fdopen(3V), however the return values differ and the normal return value is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Ablso:
QP_fclose(), QP_fopen(), QP_prepare_stream/[3,4]
{manual(i-5)}

QP_ferror()

Synopsis:
#include <quintus/quintus.h> 
          int QP_ferror(stream)

          
          QP_stream *stream;
Returns non-zero when an error has occurred reading from or writing to the named stream, otherwise zero.
QP_ferror() is similar to the UNIX C library function ferror(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fopen()
{manual(i-5)}

QP_fgetc()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fgetc(stream)

          
          QP_stream *stream;
Behaves like QP_getc(), but is a function rather than a macro.
QP_fgetc() is similar to UNIX C library function fgetc(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_ferror(), QP_fopen(), QP_fread(), QP_putc(), QP_ungetc()
{manual(i-5)}

QP_fgets()

Synopsis:
#include <quintus/quintus.h> 
          char *QP_fgets(s, n, stream)

          
          char      *s;

             int        n;

             QP_stream *stream;
Reads characters from the stream into the array pointed to by s, until n-1 characters are read, a NEWLINE character is read and transferred to s, or an EOF condition is encountered. The string is then terminated with a NULL character.
QP_fgets() is similar to the UNIX C library function fgets(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
{manual(i-5)}

QP_flush()

Synopsis:
#include <quintus/quintus.h> 
          int QP_flush(stream)

          
          QP_stream *stream;
Forces the buffered output of the stream stream to be sent to the associated device.
Arguments:
stream
pointer to a valid stream structure.
Description:
Calls the bottom layer flushing function of Stream to write out the current buffered output of the stream. The output is usually written out to a disk or a tty device.
Return Value:
QP_SUCCESS
The function succeeds
QP_ERROR
There is an error in the function call, the error number is stored in both QP_errno and stream-->errno.
Errors:
See Also:
flush_output/1.

QP_fnewln()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fnewln(stream)

          
          QP_stream *stream;
Terminates an output record for a Prolog output stream.
Arguments:
stream
pointer to a valid stream structure
See Also:
QP_newline(), QP_newln(), nl/[0,1]
{manual(i-5)}

QP_fopen()

Synopsis:
#include <quintus/quintus.h> 
          QP_stream *QP_fopen(filename, type)

          
          unsigned char *filename;

             char          *type;
Opens the file named by filename and associates a stream with it.
QP_fopen() is similar to the UNIX C library function fopen(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fopen(), QP_fdopen(), QP_prepare_stream/[3,4]
{manual(i-5)}

QP_fpeekc()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fpeekc(stream)

          
          QP_stream *stream;
Look ahead for the next character to be read in from a Prolog input stream.
Arguments:
stream
pointer to a valid stream structure
Return Value:
Character code or QP_ERROR.
See Also:
QP_peekc(), QP_peekchar(), peek_char/[1,2]

QP_fprintf()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fprintf(stream, format [ , arg ]...)

          
          QP_stream *stream;

             char      *format;
Places output onto the Prolog output stream stream.
QP_fprintf() is similar to the UNIX C library function fprintf(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_printf(), QP_putc()
{manual(i-5)}

QP_fputc()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fputc(c, stream)

          
          int        c;

             QP_stream *stream;
Behaves like QP_putc(), but is a function rather than a macro.
QP_fputc() is similar to the UNIX C library function fputc(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fclose(), QP_ferror(), QP_fopen(), QP_fread(), QP_getc(), QP_printf(), QP_puts()
{manual(i-5)}

QP_fputs()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fputs(s, stream)

          
          unsigned char *s;

             QP_stream     *stream;
Writes the NULL-terminated string pointed to by s to the named output stream.
QP_fputs() is similar to the UNIX C library function fputs(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_ferror(), QP_fopen(), QP_fread(), QP_printf(), QP_putc()
{manual(i-5)}

QP_fread()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fread (ptr, size, nitems, stream)

          
          char      *ptr;

             int        size;

             int        nitems;

             QP_stream *stream;
Reads, into a block pointed to by ptr, nitems items of data from the named input stream stream, where an item of data is a sequence of bytes (not necessarily terminated by a NULL byte) of length size.
QP_fread() is similar to the UNIX C library function fread(3S), however the return values differ slightly and stream is a Prolog stream rather than a stdio stream.
Return Value:
If the function succeeds it returns the number of items
read.
QP_ERROR
Otherwise
See Also:
QP_fopen(), QP_getc(), QP_gets(), QP_putc(), QP_puts(), QP_printf()
{manual(i-5)}

QP_fskipln()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fskipln(stream)

          
          QP_stream *stream;
Skip the current input record of a Prolog input stream
Return Value:
QP_SUCCESS, or QP_ERROR
Errors:
When QP_ERROR is returned, QP_errno contains an error code.
See Also:
skip_line/[0,1]
{manual(i-5)}

QP_fwrite()

Synopsis:
#include <quintus/quintus.h> 
          int QP_fwrite(ptr, size, nitems, stream)

          
          char      *ptr;

             int        size;

             int        nitems;

             QP_stream *stream;
Writes at most nitems items of data from the block pointed to by ptr to the named Prolog output stream. QP_fwrite() stops writing when it has written nitems of date or if an error condition is encountered on stream.
QP_fwrite() is similar to the UNIX C library function fwrite().
Return Value:
If the function succeeds it returns the number of items
written.
QP_ERROR
Otherwise
See Also:
QP_fopen(), QP_getc(), QP_gets(), QP_putc(), QP_puts(), QP_printf()
{manual(i-5)}

QP_get_*( )

Synopsis:
#include <quintus/quintus.h> 
          int QP_get_atom(term, atom)

          
          QP_term_ref      term;

             QP_atom         *atom;

          
          int QP_get_integer(term, integer)

          
          QP_term_ref      term;

             long int        *integer;

          
          int QP_get_float(term, float)

          
          QP_term_ref      term;

             double          *float;

          
          int QP_get_functor(term, name, arity)

          
          QP_term_ref      term;

             QP_atom         *name;

             int             *arity;

          
          int QP_get_arg(argnum, term, arg)

          
          int              argnum;

             QP_term_ref      term;

             QP_term_ref      arg;

          
          int QP_get_list(term, head, tail)

          
          QP_term_ref      term;

             QP_term_ref      head;

             QP_term_ref      tail;

          
          int QP_get_head(term, head)

          
          QP_term_ref      term;

             QP_term_ref      head;

          
          int QP_get_tail(term, tail)

          
          QP_term_ref      term;

             QP_term_ref      tail;

          
          int QP_get_nil(term)

          
          QP_term_ref      term;

          
          int QP_get_db_reference(term, ref)

          
          QP_term_ref      term;

             QP_db_reference *ref;
These C functions can be used to test and access Prolog terms passed to C through the foreign interface.
Description:
Examples:
write_term() is a C function that writes out a Prolog term passed to it.
IN THE PROLOG CODE:
          foreign(write_term, c, write_term(+term)).
IN THE C CODE:
          #include <quintus/quintus.h>



          void write_term(term)

          QP_term_ref term;

          {

              QP_atom a;

              long int i;

              double d;

              switch (QP_term_type(term)) {

              case QP_VARIABLE:

                  QP_printf("_");

                  break;

              case QP_INTEGER:

                  QP_get_integer(term, &i);

                  QP_printf("%d", i);

                  break;

              case QP_FLOAT:

                  QP_get_float(term, &d);

                  QP_printf("%f", d);

                  break;

              case QP_ATOM:

                  QP_get_atom(term, &a);

                  QP_printf("%s", QP_string_from_atom(a));

                  break;

              case QP_DB_REFERENCE:

                  QP_printf("'$ref'()");

                  break;

              case QP_COMPOUND:

                  if (QP_is_list(term)) {

                      write_list(term);

                  } else {

                      write_compound(term);

                  }

                  break;

              }

          }



          void write_list(term)

          QP_term_ref term;

          {

              QP_term_ref head = QP_new_term_ref();

              QP_term_ref tail = QP_new_term_ref();

              QP_atom a;



              QP_printf("[");

              QP_get_list(term, head, tail);

              write_term(head);

              while (QP_is_list(tail)) {

                  QP_printf(",");

                  QP_get_list(tail, head, tail);

                  write_term(head);

              }

              if (QP_get_nil(tail)) {

                  QP_printf("]");

              } else {

                  QP_printf("|");

                  write_term(tail);

                  QP_printf("]");


              }

          }







          void write_compound(term)

          QP_term_ref term;

          {

              int i, arity;

              QP_atom name;

              QP_term_ref arg = QP_new_term_ref();



              QP_get_functor(term, &name, &arity);

              QP_printf("%s(", QP_string_from_atom(name));

              for (i = 1; i < arity; i++) {

                  QP_get_arg(i, term, arg);

                  write_term(arg);

                  QP_printf(",");

              }

              QP_get_arg(i, term, arg);

              write_term(arg);

              QP_printf(")");

          }
See Also:
QP_term_type(), QP_put_*(), QP_new_term_ref()

QP_getchar()

Synopsis:
#include <quintus/quintus.h> 
          int QP_getchar()
Defined as QP_getc(QP_curin).
QP_getchar() is similar to the UNIX C library function getchar(3V), however it operates on the Prolog current input stream rather than the UNIX standard input stream stdin. Like getchar(3V), QP_getchar() is a macro.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_ferror(), QP_fopen(), QP_fread(), QP_gets(), QP_putc(), QP_ungetc()
{manual(i-5)}

QP_getpos()

Synopsis:
#include <quintus/quintus.h> 
          int QP_getpos(stream, pos)

          
          QP_stream   *stream;

             QP_position *pos;
Get the current position for a Prolog stream
Arguments:
stream
pointer to a valid stream structure
pos
pointer to a QP_position structure
Description:
Return Value:
Always returns QP_SUCCESS.
See Also:
QP_setpos(), QP_seek(), stream_position/[2,3], QP_char_count(), QP_line_count(), QP_line_position()
{manual(i-5)}

QP_initialize()

Synopsis:
#include <quintus/quintus.h> 
          int QP_initialize(argc, argv)

          
          int    argc;

             char **argv;
Initializes Prolog's memory management, I/O, symbol table, etc.
Arguments:
argc
number of command line arguments (or 0)
argv
list of command line arguments (or NULL)
Description:

NOTE: The first call to QP_initialize() with non-null arguments will determine the command line arguments as seen by Prolog.

Return Value:
QP_SUCCESS
Prolog was successfully initialized.
QP_FAILURE
otherwise
Examples:
See Also::
runtime_entry/1, unix/1, QP_predicate(), QP_query(), QP_toplevel()
{manual(i-2)}

QP_is_*( )

Synopsis:
#include <quintus/quintus.h> 
          int QP_is_variable(term)

          
          QP_term_ref term;

          
          int QP_is_atom(term)

          
          QP_term_ref term;

          
          int QP_is_integer(term)

          
          QP_term_ref term;

          
          int QP_is_float(term)

          
          QP_term_ref term;

          
          int QP_is_compound(term)

          
          QP_term_ref term;

          
          int QP_is_list(term)

          
          QP_term_ref term;

          
          int QP_is_db_reference(term)

          
          QP_term_ref term;

          
          int QP_is_atomic(term)

          
          QP_term_ref term;

          
          int QP_is_number(term)

          
          QP_term_ref term;
These C functions and macros can be used to test the type of the Prolog terms passed to C through the foreign interface.
Description:
QP_is_variable()
(macro) returns a nonzero value if its argument is a Prolog variable; zero otherwise.
QP_is_atom()
(macro) returns a nonzero value if its argument is an atom; zero otherwise.
QP_is_integer()
(macro) returns a nonzero value if its argument is a Prolog integer; zero otherwise.
QP_is_float()
(macro) returns a nonzero value if its argument is a float; zero otherwise.
QP_is_compound()
(macro) returns a nonzero value if its argument is a compound Prolog term; zero otherwise.
QP_is_list()
(function) returns a nonzero value if its argument is a Prolog list; zero otherwise.
QP_is_db_reference()
(macro) returns a nonzero value if its argument is a database reference; zero otherwise.
QP_is_atomic()
(function) returns a nonzero value if its argument is an atomic Prolog object; zero otherwise.
QP_is_number()
(function) returns a nonzero value if its argument is a Prolog integer or float; zero otherwise.
Examples:
print_type() is a C function that prints the type of the Prolog term passed to it.
IN THE PROLOG CODE:
          foreign(print_type, c, print_type(+term)).
IN THE C CODE:
#include <quintus/quintus.h> void print_type(term) QP_term_ref term; { if (QP_is_atom(term)) { QP_printf("Term is an atom\n"); } else if (QP_is_integer(term)) { QP_printf("Term is an integer\n"); } else if (QP_is_float(term)) { QP_printf("Term is a float\n"); } else if (QP_is_variable(term)) { QP_printf("Term is a variable\n"); } else if (QP_is_db_reference(term)) { QP_printf("Term is a database reference\n"); } else if (QP_is_compound(term)) { if (QP_is_list(term)) { QP_printf("Term is a list\n"); } else { QP_printf("Term is a compound term\n"); } } else { QP_printf("Unrecognized term\n"); } }
See Also:
QP_get_*(), QP_put_*(), QP_new_term_ref()

QP_line_count()

Synopsis:
#include <quintus/quintus.h> 
          int QP_line_count(stream)

          
          QP_stream *stream;
Obtains the line count for a Prolog stream. QP_line_count() is a macro.
Arguments:
stream
pointer to a valid stream structure
See Also:
QP_getpos(), QP_setpos(), QP_seek(), stream_position/[2,3] QP_char_count(), QP_line_position()
{manual(i-5)}

QP_line_position()

Synopsis:
#include <quintus/quintus.h> 
          int QP_line_position(stream)

          
          QP_stream *stream;
Obtains the line position for a Prolog stream. QP_line_position() is a macro.
Arguments:
stream
pointer to a valid stream structure
See Also:
QP_getpos(), QP_setpos(), QP_seek(), stream_position/[2,3] QP_char_count(), QP_line_count(),
{manual(i-5)}

QP_new_term_ref()

Synopsis:
#include <quintus/quintus.h> 
          QP_term_ref QP_new_term_ref()
Description:
Example:
create_term() is a simple C function that returns different types of Prolog terms depending on its first argument.
foreign(create_term, create_term(+integer,[-term])) #include <quintus/quintus.h> QP_term_ref create_term(kind); int kind; { QP_term_ref new = QP_new_term_ref(); switch (kind) { case 1: QP_put_integer(new, 23); break; case 2: QP_put_atom(new, QP_atom_from_string("Ayn")); break; case 3: QP_put_float(new, 1.1); break; default: QP_put_nil(new); break; } return new; }
See Also::
QP_put_*(), QP_term_type(), QP_get_*()

QP_newline()

Synopsis:
#include <quintus/quintus.h> 
          int QP_newline()
Terminates the current output record for the Prolog current output stream. QP_newline() is a macro.
Arguments:
stream
pointer to a valid stream structure
Description:
Calling QP_newline() is equivalent to call QP_newln(QP_stdout).
Return Value:
a line border character or QP_ERROR
See Also:
QP_newln(), QP_error_message(), nl/[0,1]
{manual(i-5)}

QP_newln()

Synopsis:
#include <quintus/quintus.h> 
          int QP_newln(stream)

          
          QP_stream *stream;
Terminates the current output record for a specified Prolog output stream. QP_newln() is a macro.
Arguments:
stream
pointer to a valid stream structure
Return Value:
a line border character or QP_ERROR
See Also:
QP_newline(), QP_error_message(), nl/[0,1]
{manual(i-5)}

QP_next_solution()

Synopsis:
#include <quintus/quintus.h> 
          int QP_next_solution(qid)

          
          QP_qid qid;
Returns the next solution (if any) from an open nondeterminate Prolog query.
Description:
Comment:
An important restriction: only the innermost, i.e. the most recent, open query can be asked to compute a solution. A new nondeterminate query can be made at any point whether or not other queries are open; however, while the new query remains open only it will be able to return solutions. Of course, determinate queries can be made at any time.
Return Values:
QP_SUCCESS
Solution found
QP_FAILURE
No solution found
QP_ERROR
See Also:
QP_cut_query(), QP_close_query(), QP_query(), QP_open_query(), QP_pred(), QP_predicate(),
{manual(i-4)}

QP_open_query()

Synopsis:
#include <quintus/quintus.h> 
          QP_qid QP_open_query(pred_ref, arg1,...,arg255)

          
          QP_pred_ref pred_ref;
Initiates a nondeterminate Prolog query.
Description:
Return Value:
QP_qid
query was opened successfully
QP_ERROR
an error occurred when attempting to open the query and the query was automatically terminated
See Also:
QP_cut_query(), QP_close_query(), QP_query(), QP_next_solution(), QP_pred(), QP_predicate(),
{manual(i-4)}

QP_peekc()

Synopsis:
#include <quintus/quintus.h> 
          int QP_peekc(stream)

          
          QP_stream *stream;
Look a character ahead from a specified Prolog input stream. QP_peekc() is a macro.
Arguments:
stream
pointer to a valid stream structure
Return Value:
Character code or QP_ERROR.
See Also:
QP_peekchar(), QP_fpeekc(), peek_char/[1,2]
{manual(i-5)}

QP_peekchar()

Synopsis:
#include <quintus/quintus.h> 
          int QP_peekchar()
Look a character ahead from the Prolog current input stream. QP_peekchar() is a macro.
Description:
QP_peekchar() is equvalent to QP_peekc(QP_stdin).
Return Values:
Character code or QP_ERROR.
See Also:
QP_peekc(), QP_fpeekc(), peek_char/[2,3]
{manual(i-5)}

QP_perror()

Synopsis:
#include <quintus/quintus.h> 
          void QP_perror(s)

          
          char *s;
Description:
QP_perror() produces a short error message on the stream user_error describing the last error encountered. If s is not a NULL pointer and does not point to a null string, the string it points to is printed, followed by a colon, followed by a space, followed by the message and a NEWLINE. If s is a NULL pointer or points to a null string, just the message is printed, followed by a NEWLINE. To be of most use, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable QP_errno (see {manual(m-1)}), which is set when errors occur but not cleared when non-erroneous calls are made.
This function is modeled on the UNIX function perror(3).
See Also:
QP_error_message()

QP_pred()

Synopsis:
#include <quintus/quintus.h> 
          QP_pred_ref QP_pred(name_atom, arity, module_atom)

          
          QP_atom name_atom;

             int     arity;

             QP_atom module_atom;
Looks up a callable Prolog predicate.
QP_pred() is faster, but less convenient, than QP_predicate()
Description:
Differences from QP_predicate():
Return Value:
QP_pred_ref
a valid predicate reference
QP_ERROR
if the predicate called hasn't been declared callable or doesn't exist
See Also:
QP_predicate(), QP_query(), QP_open_query(), QP_next_solution(), QP_cut_query(), QP_close_query(), {manual(i-4)}

QP_predicate()

Synopsis:
#include <quintus/quintus.h> 
          QP_pred_ref QP_predicate(name_string, arity,

                                   module_string)

          
          char *name_string;

             int   arity;

             char *module_string;
Description:
Return Value:
QP_pred_ref
a valid predicate reference
QP_ERROR
if the predicate called hasn't been declared callable or doesn't exist
See Also:
QP_pred(), QP_query(), QP_open_query(), QP_next_solution(), QP_cut_query(), QP_close_query()
{manual(i-4)}

QP_prepare_stream()

Synopsis:
#include <quintus/quintus.h> 
          void QP_prepare_stream(stream, buffer)

          
          QP_stream     *stream;

             unsigned char *buffer;
Initialize internal fields of a QP_stream structure.
Arguments:
stream
pointer to a valid stream structure
buffer
pointer to a buffer
Description:
Example:
QP_prepare_stream(&stream->qpinfo, stream->buffer);
See Also:
QP_fdopen(), QP_fopen(), open/[3,4],
{manual(i-5-5-6)}

QP_printf()

Synopsis:
#include <quintus/quintus.h> 
          int QP_printf(format [ , arg ] ... )

          
          char *format;
Places output onto the current Prolog output stream.
QP_printf() is similar to the UNIX C library function printf(3V), however the return values differ it puts its output on the current Prolog output stream (QP_curout) rather than a stdio stream.
Return Value:
If the function succeeds it returns the number characters
written.
QP_ERROR
Otherwise
See Also:
QP_putc()
{manual(i-5)}

QP_put_*()

Synopsis:
These C functions can be used to create new Prolog terms from C.
#include <quintus/quintus.h> 
          void QP_put_variable(term)

          
          QP_term_ref     term;

          
          void QP_put_atom(term, atom)

          
          QP_term_ref     term;

             QP_atom         atom;

          
          void QP_put_integer(term, integer)

          
          QP_term_ref     term;

             long int        integer;

          
          void QP_put_float(term, float)

          

          QP_term_ref     term;

             double          float;

          
          void QP_put_functor(term, name, arity)

          
          QP_term_ref     term;

             QP_atom         name;

             int             arity;

          
          void QP_put_list(term)

          
          QP_term_ref     term;

          
          void QP_put_nil(term)

          
          QP_term_ref     term;

          
          void QP_put_term(term1, term2)

          
          QP_term_ref     term1;

             QP_term_ref     term2;

          
          void QP_put_db_reference(term, ref)

          
          QP_term_ref     term1;

             QP_db_reference ref;
Description:
QP_put_variable() assigns to term a reference to a
new unbound Prolog variable.
QP_put_atom() assigns to term a reference to the
atom represented by atom. atom is assumed to be the canonical representation of a Prolog atom, either obtained from Prolog or returned by QP_atom_from_string().
QP_put_integer() assigns to term a reference to
integer tagged as a Prolog term.
QP_put_float() assigns to term a reference to the
floating point number float tagged as a Prolog term.
QP_put_functor() assigns to term a reference to a
new compound term whose functor is the atom represented by name and whose arity is arity. All the args of the compound term are unbound. This is similar to the Prolog builtin functor/3 with its first argument unbound and its second and third argument bound.
QP_put_list() assigns to term a reference to a new
list whose head and tail are both unbound.
QP_put_nil() assigns to term a reference to the
atom '[]'.
QP_put_term() assigns to term1 a reference to the
term that term2 references. Any reference to another term that term1 contained is lost.
QP_put_db_reference() assigns to term a reference
to the Prolog database reference represented by ref. ref must have been a reference obtained through QP_get_db_reference(). Any reference to another term that term1 contained is lost.
Examples:
flt_to_chars() is a C function that converts a floating point number to a list of characters. Note the use of QP_put_integer().
IN THE PROLOG CODE:
foreign(flt_to_chars, flt_to_chars(+float, -term)).
IN THE C CODE:
#include <quintus/quintus.h> void flt_to_chars(flt, chars) float flt; QP_term_ref chars; { char buffer[28], *p; int len; QP_term_ref term_char = QP_new_term_ref(); QP_put_nil(chars); sprintf( buffer , "%.17e" , flt ); /* move to end of buffer */ for (p=buffer, len=0; *p; p++, len++); while ( len-- ) { QP_put_integer(term_char, *--p); QP_cons_list(chars, term_char, chars); } }
See Also:
QP_term_type(), QP_get_*(), QP_new_term_ref()

QP_puts()

Synopsis:
#include <quintus/quintus.h> 
          int QP_puts(s)

          
          unsigned char *s;
Writes the NULL-terminated string pointed to by s, followed by a NEWLINE character, to the Prolog current output stream QP_curout.
QP_puts() is similar to the UNIX C library function puts(3S), however it operates on the Prolog current output stream rather than the UNIX standard output stream stdout.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_ferror(), QP_fopen(), QP_fread(), QP_printf(), QP_putc()
{manual(i-5)}

QP_query()

Synopsis:
#include <quintus/quintus.h> 
          int QP_query(pred_ref, arg1,...,arg255)

          
          QP_pred_ref pred_ref;
Make a determinate query in a single C function call.
Description:
Return Value:
QP_SUCCESS
query was made and a solution to the query was computed
QP_FAILURE
query was made but no solution could be found
QP_ERROR
either the query could not be made, or that an exception was signaled from Prolog but not caught.
See Also:
QP_cut_query(), QP_close_query(), QP_next_solution(), QP_open_query(), QP_pred(), QP_predicate(), {manual(i-4)}

QP_register_atom(), QP_unregister_atom()

Synopsis:
#include <quintus/quintus.h> 
          int QP_register_atom(atom)

          
          QP_atom atom;

          
          int QP_unregister_atom(atom)

          
          QP_atom atom;
Description:
Return Value:
the current reference count of the atom or QP_ERROR if an error occurs.
Tips:
Atoms do not normally need to be registered when calling foreign code. The only situation where this is needed is when the atom is being stored in a global or static data structure before returning to Prolog code, to be accessed subsequently by later calls to the foreign code.
See Also:
garbage_collect_atoms/0

QP_register_stream()

Synopsis:
#include <quintus/quintus.h> 
          long QP_register_stream(stream)

          
          QP_stream *stream;
Register a created Prolog stream.
Arguments:
stream
pointer to a valid stream structure
Description:
A customized Prolog stream must be registered via a call to QP_register_stream() before it can be accessed in Prolog code.
See Also:
stream_code/2
{manual(i-5-5-6)}

QP_remove_*()

Synopsis:
#include <quintus/quintus.h> 
          int QP_remove_input(id)

          
          int  id;

          
          int QP_remove_output(id)

          
          int  id;

          
          int QP_remove_exception(id)

          
          int  id;

          
          int QP_remove_timer(timerid)

          
          int  timerid;
These C functions remove registered input/output or timing callback functions.
Description:
Return Values:
QP_SUCCESS if the callback is removed
QP_ERROR otherwise
See Also:
QP_add_*(), QP_select(), QP_wait_input()

QP_rewind()

Synopsis:
#include <quintus/quintus.h> 
          int QP_rewind(stream)

          
          QP_stream *stream;
QP_rewind() is similar to the UNIX C library function rewind(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fopen(), QP_ungetc()
{manual(i-5)}

QP_seek()

Synopsis:
#include <quintus/quintus.h> 
          int QP_seek(stream, offset, whence)

          
          QP_stream *stream;

             long int   offset;

             int        whence;
Seeks to an arbitrary byte position on the stream.
Arguments:
stream
pointer to a valid stream structure.
offset
the offset in bytes to seek relative to whence specified.
whence
specifies where to start seeking. It is one of the following.
QP_BEGINNING
seek from beginning of the file stream. The new position of the file stream is set to offset bytes.
QP_CURRENT
seek from current position of the file stream. The new position of the file stream is set to its current location plus offset.
QP_END
seek from end of the file stream. The new position of the file stream is set to the size of the file plus offset.
Description:
Return Value:
QP_SUCCESS
The function succeeds
QP_ERROR
There is an error in function call, the error number is stored in both QP_errno and stream-->errno.
Errors:
Tips:
QP_seek(stream, 0L, QP_CURRENT) sets the current position to the magic field of stream. It does not change the position of stream, but the side effect of flushing output and clearing buffer also takes place.
Comments:
Examples:
Get the current byte offset from beginning of the file stream.
          if (QP_seek(stream, 0L, QP_CURRENT) != QP_SUCCESS)

                  QP_perror(stream-->errno, "QP_seek");

          else

                  location = stream-->magic.byteno;
See Also:
QP_getpos(), QP_setpos(), QP_rewind(), QP_flush().
{manual(i-5)}

QP_select()

Synopsis:
#include <quintus/quintus.h> 
          int QP_select(wid,read_fds,write_fds,except_fds,timeo)

          
          int    wid;

             fd_set *read_fds;

             fd_set *write_fds;

             fd_set *except_fds;

             struct timeval *timeo;
Wait until I/O is ready on a file descriptor or until a timeout occurs
Description:
Return Values:
the number of descriptors in the bit mask, QP_SUCCESS if a timeout occurred or QP_ERROR if an error occurred.
See Also:
QP_wait_input(), QP_add_*()

QP_setinput()

Synopsis:
#include <quintus/quintus.h> 
          QP_stream *QP_setinput(stream)

          
          QP_stream *stream;
Set the Prolog current input stream to a specified value stream.
Arguments:
stream
pointer to a valid input stream
Description:
See Also:
set_input/1, QP_setoutput()
{manual(i-5)}

QP_setoutput()

Synopsis:
#include <quintus/quintus.h> 
          QP_stream *QP_setoutput(stream)

          
          QP_stream *stream;
Set the Prolog current output stream to a specified value stream.
Arguments:
stream
pointer to a valid Prolog output stream
Description:
This function sets the current Prolog outpout stream to stream and returns the previous current Prolog output stream before the operation.
See Also:
set_ouptut/1, QP_setinput()
{manual(i-5)}

QP_setpos()

Synopsis:
#include <quintus/quintus.h> 
          int QP_setpos(stream, pos)

          
          QP_stream   *stream;

             QP_position *pos;
Reset a specified Prolog stream back to a previous read/written position.
Arguments:
stream
pointer to a valid stream structure
pos
pointer to a QP_position structure.
The stream count is set the system-dependent file position to be reposition char_count, line_count, line_position and magic member of the QP_position structure pointed by pos have the valid values indicating the current character count, line count, line position and system-dependent position.
Description:
See Also:
QP_getpos(), QP_seek(), stream_position/[2,3] QP_char_count(), QP_line_count(), QP_line_position()
{manual(i-5)}

QP_skipline()

Synopsis:
#include <quintus/quintus.h> 
          int QP_skipline()
Skip the current input record of the current Prolog input stream. QP_skipline() is a macro.
Description:
QP_skipline() is equivalent to QP_skipln(QP_curin).
See Also:
QP_skipln()
{manual(i-5)}

QP_skipln()

Synopsis:
#include <quintus/quintus.h> 
          int QP_skipln(stream)

          
          QP_stream *stream;
Skip the current input record of a Prolog input stream. QP_skipln() is a macro.
Arguments:
stream
pointer to a valid Prolog input stream
See Also:
QP_skipline(), QP_fskipln()
{manual(i-5)}

QP_string_from_atom(), QP_padded_string_from_atom()

Synopsis: 
          char *QP_string_from_atom(atom)

          
          QP_atom atom;

          
          int

          QP_padded_string_from_atom(p_atom, p_string, p_length)

          
          QP_atom *p_atom;

             char    *p_string;

             int     *p_length;
Description:
Examples:
rev_atom() is a C function that takes an atom and returns an atom whose string representation is the reverse of the string representation of the atom passed in.
          foreign(rev_atom, c, rev_atom(+atom, [-atom])).



          QP_atom rev_atom(atom)

          QP_atom atom;

          {

              char * string[MAX_ATOM_LEN];



              strcpy(string, QP_string_from_atom(atom));

              reverse(string); /* reverses string in place */

              return QP_atom_from_string(string);

          }



          | ?- rev_atom(draw, X).



          X = ward



          yes

          | ?-
See Also:
QP_atom_from_string(), QP_atom_from_padded_string()
{manual(i-3-7)}

QP_tab()

Synopsis:
#include <quintus/quintus.h> 
          int QP_tab(stream, count, c)

          
          QP_stream *stream;

             int        count;

             int        c;
Output count number of the character c on Prolog output stream stream.
Arguments:
stream
pointer to a valid Prolog output stream
count
how many characters of c to be output
c
character to be written out
Examples:
QP_tab(QP_curout, 5, ' ') puts 5 blank characters to the current output stream.
See Also:
QP_tabto()

QP_tabto()

Synopsis:
#include <quintus/quintus.h> 
          int QP_tabto(stream, line_pos, c)

          
          QP_stream *stream;

             int        line_pos;

             int        c;
Pad the character c up to the specified line position line_pos on Prolog output stream stream.
Arguments:
stream
pointer to a valid Prolog output stream
line_pos
line position to be padded to.
c
character used for padding
See Also:
QP_tab()

QP_term_type()

Synopsis:
#include <quintus/quintus.h> 
          int QP_term_type(term)

          
          QP_term_ref term;
Tests the type of Prolog terms in C.
Description:
QP_term_type() returns the type of a Prolog term which is passed to it as argument. The returned value is one of the following constants defined in the file #include <quintus/quintus.h>: QP_VARIABLE, QP_INTEGER, QP_ATOM, QP_FLOAT or QP_COMPOUND.
Examples:
print_type() is a C function that prints the type of the Prolog term passed to it.
IN THE PROLOG CODE:
          foreign(print_type, c, print_type(+term)).
In The C Code:
#include <quintus/quintus.h> void print_type(term) QP_term_ref term; { switch (QP_term_type(term)) { case QP_VARIABLE: QP_printf("Term is a variable\n"); break; case QP_INTEGER: QP_printf("Term is an integer\n"); break; case QP_FLOAT: QP_printf("Term is a float\n"); break; case QP_ATOM: QP_printf("Term is an atom\n"); break; case QP_COMPOUND: if (QP_is_list(term)) { QP_printf("Term is a list\n"); } else { QP_printf("Term is a compound term\n"); } break; } }
See Also:
QP_is_*(), QP_get_*(), QP_put_*(), QP_new_term_ref()

QP_toplevel()

Synopsis:
#include <quintus/quintus.h> 
          int QP_toplevel()
Description:
Invokes Prolog's default top level read-prove loop.
For runtime systems, QP_toplevel() immediately transfers control to the definition of the Prolog predicate runtime_entry/1.
QP_toplevel() takes no arguments. QP_query() and related predicates should be used for calling specific Prolog predicates.
One of the effects of calling this function is that the default signal handling for Prolog is enabled. Upon return, the old signal handlers are restored.
The built-in predicate break/0 calls this function. Nested calls to this function are equivalent to calling the Prolog predicate break/0.
This function returns when an end-of-file character is read.
Return Value:
QP_SUCCESS QP_FAILURE QP_ERROR.
See Also:
QP_initialize(), break/0.

QP_trimcore()

Synopsis: 
          int QP_trimcore()
QP_trimcore() is the C equivalent of Prolog's trimcore/0.
Description:
See Also:
trimcore/0
{manual(i-2)}

QP_ungetc()

Synopsis:
#include <quintus/quintus.h> 
          int QP_ungetc(c, stream)

          
          int        c;

             QP_stream *stream;
Pushes the character c back onto Prolog input stream stream.
QP_ungetc() is similar to the UNIX C library function ungetc(3S), however the return values differ and stream is a Prolog stream rather than a stdio stream.
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_fseek(), QP_getc()
{manual(i-5)}

QP_unify()

Synopsis:
#include <quintus/quintus.h> 
          int QP_unify(term1, term2)

          
          QP_term_ref term1;

             QP_term_ref term2;
Unify two Prolog terms.
Description:
QP_unify() unifies the two terms referenced by term1 and term2. Both should be initialized references. If the unification succeeds, the function returns QP_SUCCESS, otherwise it returns QP_FAILURE. If the unification results in any bindings then the bindings are trailed. If Prolog backtracks over the foreign function that called QP_unify() then the bindings are undone.
Examples:
c_unify(term1, term2) is equivalent to the usual Prolog builtin =/2, but it returns a third argument which is an integer indicating success or failure.
IN THE PROLOG CODE:
foreign(c_unify, c, c_unify(+term, +term, [-integer]))
IN THE C CODE:
#include <quintus/quintus.h> int c_unify(t1, t2); QP_term_ref t1, t2; { return QP_unify(t1, t2); }
See Also:
=/2

QP_vfprintf()

Synopsis:
#include <quintus/quintus.h> 
          int QP_vfprintf(stream, format, ap)

          
          QP_stream *stream;

             char      *format;

             va_list    ap;
Places output onto the Prolog output stream stream.
QP_vfprintf() is also similar to the UNIX C library function vfprintf(3V), however the return values differ and stream is a Prolog stream rather than a stdio stream. It also resembles QP_fprintf() except that rather than being called with a variable number of arguments, it is called with an argument list as defined by varargs(3).
Return Value:
QP_SUCCESS
If function succeeds
QP_ERROR
Otherwise
See Also:
QP_printf(), QP_fprintf()
{manual(i-5)}

QP_wait_input()

Synopsis:
#include <quintus/quintus.h> 
          int QP_wait_input(id,timeout)

          
          int id;

             int *timeout;
Wait until I/O is ready on a file descriptor or until a timeout occurs
Description:
Return Values:
QP_SUCCESS
if input arrived on id
QP_FAILURE
if a timeout occurred
QP_ERROR
if an error occurs
See Also:
QP_select(), QP_add_*()

QU_alloc_mem(), QU_alloc_init_mem(), QU_free_mem()

Synopsis: 
          char *QU_alloc_mem(size, alignment, actualsize)

          
          unsigned long  size;

             unsigned long  alignment;

             unsigned long *actualsize;
The primitive function that Prolog calls to get memory 
          char *QU_alloc_init_mem(size, alignment, actualsize)

          
          unsigned long  size;

             unsigned long  alignment;

             unsigned long *actualsize;

Called when Prolog needs memory for the first time 

          int QU_free_mem(mem, size)

          
          char          *mem;

             unsigned long  size;

The primitive function called when Prolog wants to free memory.

Description:
These are the primitive functions on which the all of Prolog's sophisticated memory management is built. If Prolog is to be embedded into an application which would like to provide its own memory management routines then the user can redefine these functions and link it with the Prolog system.
The default definitions for these functions look at the environment variables PROLOGINITSIZE, PROLOGINCSIZE, PROLOGKEEPSIZE and PROLOGMAXSIZE. These environment variables are useful to customize the default memory manager. If users redefine this layer of memory management they can choose to ignore these environment variables.
Examples:
Here is a simple example of the embeddable layer of memory management based on malloc(3) and free(3). This example is far from ideal because you might be over-allocating memory to ensure the required size of aligned memory, but demonstrates the capability. The C file mem.c defines QU_alloc_mem(), QU_alloc_init_mem() and QU_free_mem().
IN THE C CODE: mem.c:
unsigned long IncSize = 0x100000; /* 1M */ unsigned long InitSize = 0x100000; /* 1M */ unsigned long MaxSize = 0x1000000; /* 16 M */ unsigned long KeepSize = 0x100000; /* 1M */ unsigned long MemTotal; char * QU_alloc_mem(size, align, actualsize) unsigned long size; /* in bytes */ unsigned long align; /* power of 2 */ unsigned long *actualsize; { char *mem, *malloc(); size = size + align; if (size <= IncSize) size = IncSize; if ((size + MemTotal) > MaxSize) return 0; mem = malloc(size); *actualsize = size; MemTotal += (mem == 0 ? 0 : size); return mem; } char * QU_alloc_init_mem(size, align, actualsize) unsigned long size; /* in bytes */ unsigned long align; /* power of 2 */ unsigned long *actualsize; { char *mem, *str, *malloc(), *getenv(); str = getenv("PROLOGINCSIZE"); if (str) sscanf(str, "%u", &IncSize); str = getenv("PROLOGINITSIZE"); if (str) sscanf(str, "%u", &InitSize); str = getenv("PROLOGMAXSIZE"); if (str) sscanf(str, "%u", &MaxSize); str = getenv("PROLOGKEEPSIZE"); if (str) sscanf(str, "%u", &KeepSize); MemTotal = 0; return QU_alloc_mem(size, align, actualsize); } int QU_free_mem(mem, size) char * mem; unsigned long size; { if ((MemTotal - size) < KeepSize) return 0; free(size); MemTotal = MemTotal - size; return 1; }
AT THE COMMAND LEVEL: To build an Prolog development system based on the functions defined in mem.c:
                  1. cc -c mem.c

                  2. qld -D mem.o -o prolog_on_my_mm_fns
See Also:
{manual(i-2)}

QU_fdopen() user-redefinable

Synopsis: 
          QP_stream *QU_fdopen(stream_option, system_option,

                               error_number, file_des)

          
          QP_stream *stream_option;

             char      *system_option;

             int       *error_number;

             int        file_des;
The embedding function for creating a stream opened through open/[3,4] or QP_fopen(). Creates a stream and returns the QP_stream pointer for that stream.
Description:
QU_fdopen() is similar to QU_open() except that the file stream is already opened and the opened UNIX file descriptor is passed through the parameter file_des.
Examples:
See the example in the manual page for QU_open().
See Also:
QU_open(), {manual(i-5)}

QU_free_mem() user-redefinable

Described in reference page for QU_alloc_mem().

QU_initio() user-redefinable

Synopsis:
#include <quintus/quintus.h> 
          int QU_initio(user_input, user_output, user_error,

                                   act_astty, error_num)

          
          QP_stream **user_input;

             QP_stream **user_output;

             QP_stream **user_error;

             int         act_astty;

             int        *error_num;
Initializes Prolog input/output system. Returns QP_SUCCESS upon success and QP_ERROR upon failure.
Description:
Tip:
The process required to create these three initial streams is similar to that of implementing a customized Prolog stream. (see {manual(i-5-5)}). However, these three initial streams should not be registered. Calling QP_register_stream() to register any of the three streams created by QU_initio() may cause an error when Prolog starts up.
Examples:
The following is the source code for an implementation of QU_initio() function in C language. 
#include <sys/types.h>

#include <sys/stat.h>



#include "quintus.h"



#define TTY_BUFSIZ              128

#define MAX_FIFO_BUFSIZ         4096



extern  QP_stream    *QU_fdopen();



/*

 *  This I/O initialization function only handles three possible

 *  types of file, a tty file , a pipe and an ordinary file

 */

int QU_initio(user_input, user_output, user_error, act_astty,

                          error_num)

    QP_stream   **user_input, **user_output, **user_error;

    int         act_astty, *error_num;

    {

        int             fd, is_tty;

        struct  stat    statbuf;

        QP_stream       option, *streams[3], *prompt_stream;

        extern char     *ttyname();



        for (fd=2; fd >= 0 ; --fd) {

            is_tty = isatty(fd);

            QU_stream_param((is_tty) ? "/dev/tty" : "",

                        (fd) ? QP_WRITE : QP_READ, &option);

            if (is_tty || act_astty) {

                /* make sure other parameters are right  */

                option.format     = QP_DELIM_TTY;

                option.max_reclen = TTY_BUFSIZ;

                option.seek_type  = QP_SEEK_ERROR;

                if (fd == 0)

                    option.peof_act = QP_PASTEOF_RESET;

            } else  {

                if (fstat(fd, &statbuf) < 0)

                    return QP_ERROR;

                if ((statbuf.st_mode & S_IFIFO) == S_IFIFO) {

                    option.max_reclen = MAX_FIFO_BUFSIZ;

                    option.seek_type  = QP_SEEK_ERROR;

                } else

                    option.max_reclen = statbuf.st_blksize;

            }

            option.mode = (fd) ? QP_WRITE : QP_READ;

            if ((streams[fd]=QU_fdopen(&option,"",error_num,fd))

                                ==QP_NULL_STREAM)

                return QP_ERROR;

            if (is_tty) {

                char        *tty_id;

                if (! (tty_id = ttyname(fd)) )

                    tty_id = "/PROLOG DEFAULT TTYS";

                (void) QP_add_tty(streams[fd], tty_id);

            } else if (act_astty)

                (void) QP_add_tty(streams[fd],

                                  "/PROLOG INITAIL STREAMS");

        }

        (streams[0])->filename="USER$INPUT";

        *user_input  = streams[0];

        (streams[1])->filename="USER$OUTPUT";

        *user_output = streams[1];

        (streams[2])->filename="USER$ERROR";

        *user_error  = streams[2];

        if ((streams[0])->format == QP_DELIM_TTY

                && (streams[1])->format != QP_DELIM_TTY

                && (streams[2])->format != QP_DELIM_TTY) {

            char *tty_id;

            /* create an output stream for prompt */

            QU_stream_param(isatty(0) ? "/dev/tty" : "", QP_WRITE,

                                            &option);

            option.format = QP_DELIM_TTY;

            option.max_reclen = TTY_BUFSIZ;

            option.seek_type = QP_SEEK_ERROR;

            if ((prompt_stream = QU_fdopen(&option, "", error_num,

                               0)) == QP_NULL_STREAM)

                return QP_ERROR;



            (void) QP_register_stream(prompt_stream);

            if (! (tty_id = ttyname(0)) )

                tty_id = "/PROLOG DEFAULT TTYS";

            (void) QP_add_tty(prompt_stream, tty_id);

        }

        return QP_SUCCESS;

    }

QU_open() user-redefinable

Synopsis:
#include <quintus/quintus.h> 
          QP_stream *QU_open(stream_option, system_option,

                                         error_number)

          
          QP_stream *stream_option;

             char      *system_option;

             int       *error_number;
The embedding function for creating a stream opened through open/[3,4] or QP_fopen().
Creates a stream and returns the QP_stream pointer for that stream.
Description:
Return Value:
If any error occurs during the creation of the stream, QP_NULL_STREAM is returned and the error code for the error condition is set in the third parameter, error_number. The error code could be any of the host operating system error numbers, QP error numbers or a user-defined error number. QU_fdopen() is only defined for the Prolog system running under UNIX operating system. It requires an addition parameter, file_des, which is the opened file descriptor for the stream to be created.
Examples:
The following is the source code for an implementation of QU_open() function and QU_fdopen() function in C.
See Also:
open/4, QU_fdopen()
{manual(i-5)}

QU_stream_param() user-redefinable

Synopsis:
#include <quintus/quintus.h> 
          void QU_stream_param(filename, mode, format, option)

          
          char          *filename;

             int            mode;

             unsigned char  format;

             QP_stream     *option;
Embedding function which sets up default values of user-accessible fields in a Prolog stream structure.
Arguments:
filename
name of the file to be opened. If the stream does not have a file name, the filename is the empty string, "". If the filename is "/dev/tty", the caller requests QU_stream_param() to set the field values as a tty stream.
mode
QP_READ for an input stream. QP_WRITE for an output stream QP_APPEND for an output stream opened in append mode.
format
format of the stream, which could have one of the following values:
option
pointer to a QP_stream structure whose fields are to be set up.
Description: The format is used in assisting QU_stream_param() to
determine the best values for the other member fields of the QP_stream structure.
All of the fields listed below of the QP_stream structure, described in the Stream Structure section of Input/Output chapter ({manual(i-5-3)}), are set by QU_stream_param(). On UNIX, they are given the indicated values:
field
value
<Courier>
<Helvetica>
filename
filename argument to QU_stream_param()
mode
mode argument to QU_stream_param()
format
format argument to QU_stream_param()
max_reclen
8192 bytes for a file, 256 bytes for a tty
line_border
QP_LF
file_border
QP_EOF
peof_act
QP_PASTEOF_ERROR
prompt
"" (empty string)
trim
0
seek_type
QP_SEEK_PREVIOUS for a file QP_SEEK_ERROR for a tty
flush_type
QP_FLUSH_FLUSH
overflow
QP_OV_FLUSH
errno
0
magic
(byteno) 0
read
"bad_read" - a function that returns QP_ERROR
write
"bad_write" - a function that returns QP_ERROR
flush
"bad_flush" - a function that returns QP_ERROR
seek
"bad_seek" - a function that returns QP_ERROR
close
"bad_close" - a function that returns QP_ERROR

n: Command Reference Pages

Copyright (C) 1997 AI International Ltd
contact: product support sales information