From 593f7ee64fcb52eb86a9cc2a8644b05b3d170b37 Mon Sep 17 00:00:00 2001 From: vsc Date: Thu, 24 May 2001 15:26:41 +0000 Subject: [PATCH] small bug fixes and documentation for extra C-functions. git-svn-id: https://yap.svn.sf.net/svnroot/yap/trunk@42 b08c6af1-5177-4d33-ba66-4b1c6b8b522a --- C/c_interface.c | 3 +- C/save.c | 2 +- TO_DO | 4 +- docs/yap.tex | 118 +++++++++++++++++++++++++++++++++++++++++------- 4 files changed, 106 insertions(+), 21 deletions(-) diff --git a/C/c_interface.c b/C/c_interface.c index 8d5295c3b..32c534021 100644 --- a/C/c_interface.c +++ b/C/c_interface.c @@ -99,7 +99,8 @@ X_API void STD_PROTO(YapExit, (int)); X_API void STD_PROTO(YapInitSocks, (char *, long)); X_API void STD_PROTO(YapSetOutputMessage, (void)); X_API int STD_PROTO(YapStreamToFileNo, (Term)); -X_API int STD_PROTO(YapPopen, (Term)); +X_API void STD_PROTO(YapCloseAllOpenStreams,(void)); +X_API Term STD_PROTO(YapOpenStream,(void *, char *, Term, int)); X_API Term YapA(int i) diff --git a/C/save.c b/C/save.c index cf143008f..81d26a0f6 100644 --- a/C/save.c +++ b/C/save.c @@ -2430,7 +2430,7 @@ RestoreEntries(PropEntry *pp) break; case ArrayProperty: { - ArrayEntry *ae = (ArrayEntry *)ae; + ArrayEntry *ae = (ArrayEntry *)pp; if (ae->ArrayEArity < 0) { restore_static_array((StaticArrayEntry *)ae); } else { diff --git a/TO_DO b/TO_DO index d7402da76..5f23d5d2b 100644 --- a/TO_DO +++ b/TO_DO @@ -13,8 +13,6 @@ BEFORE 4.4: - library(system) for WIN32 - document system(library) - document new interface functions. -- logtalk. -- listing (Steve Moyle). TO CHECK: - bad register allocation for a(X,Y) :- X is Y+2.3 ? @@ -70,3 +68,5 @@ DONE: - copying garbage collector: implemented hybrid - dif example in Manual. - initial port to OS_X +- listing (Steve Moyle). +- logtalk. diff --git a/docs/yap.tex b/docs/yap.tex index c33429e9b..bb2797063 100644 --- a/docs/yap.tex +++ b/docs/yap.tex @@ -221,6 +221,7 @@ Subnodes of Library * RegExp:: Regular Expression Manipulation * Splay Trees:: Splay Trees * String I/O:: Writing To and Reading From Strings +* System:: System Utilities * Terms:: Utilities on Terms * Timeout:: Call With Timeout * Trees:: Updatable Binary Trees @@ -280,6 +281,18 @@ Subnodes of CHR * CHR Constraint Handlers:: * CHR Backward Compatibility:: +Subnodes of C-Interface +* Manipulating Terms:: Primitives available to the C programmer +* Unifying Terms:: How to Unify Two Prolog Terms +* Manipulating Strings:: From character arrays to Lists of codes and back +* Memory Allocation:: Stealing Memory From Yap +* Controlling Streams:: Control How Yap sees Streams +* Calling Yap From C:: From C to Yap to C to Yap +* Writing C:: Writing Predicates in C +* Loading Objects:: Loading Object Files +* Sav&Rest:: Saving and Restoring +* Yap4 Notes:: Changes in Foreign Predicates Interface + Subnodes of C-Prolog * Major Differences with C-Prolog:: Major Differences between YAP and C-Prolog * Fully C-Prolog Compatible:: Yap predicates fully compatible with @@ -797,7 +810,7 @@ CC="cc -64" $YAP_SRC_PATH/configure --... We next describe how to invoke Yap in Unix systems. @section Running Yap Interactively -@node Interactive Mode, Script Mode, ,Running Yap +@node Interactive Mode, Script Mode, ,Run Most often you will want to use Yap in interactive mode. Assuming that YAP is in the user's search path, the top-level can be invoked under @@ -865,7 +878,7 @@ first. If it cannot it will use the environment variable YAPLIBDIR, if defined, or search the default library directory. @section Running Yap as a script -@node Script Mode, ,Interactive Mode, Running Yap +@node Script Mode, ,Interactive Mode, Run YAP can also be used to run Prolog files as scripts, at least in Unix-like environments. A simple example is shown next: @@ -6204,6 +6217,7 @@ Library, Extensions, Builtins, Top * RegExp:: Regular Expression Manipulation * Splay Trees:: Splay Trees * String I/O:: Writing To and Reading From Strings +* System:: System Utilities * Terms:: Utilities on Terms * Timeout:: Call With Timeout * Trees:: Updatable Binary Trees @@ -7060,7 +7074,7 @@ Construct and return two trees @var{LeftTree} and @var{RightTree}, where @end table -@node String I/O, Terms, Splay Trees, Library +@node String I/O, System, Splay Trees, Library @section Reading From and Writing To Strings @cindex string I/O @@ -7215,7 +7229,11 @@ importing these built-ins. YAP does not currently support opening a @code{charsio} stream in @code{append} mode, or seeking in such a stream. -@node Terms, Timeout, String I/O, Library +@node System, Terms, String I/O, Library +@section Calling The Operating System from YAP +@cindex Operating System Utilities + +@node Terms, Timeout, System, Library @section Utilities On Terms @cindex utilities on terms @@ -11623,13 +11641,18 @@ The rest of this appendix describes exhaustively how to interface C to YAP. @menu * Manipulating Terms:: Primitives available to the C programmer -* WritingC:: Writing Predicates in C -* LoadingO:: Loading Object Files +* Unifying Terms:: How to Unify Two Prolog Terms +* Manipulating Strings:: From character arrays to Lists of codes and back +* Memory Allocation:: Stealing Memory From Yap +* Controlling Streams:: Control How Yap sees Streams +* Calling Yap From C:: From C to Yap to C to Yap +* Writing C:: Writing Predicates in C +* Loading Objects:: Loading Object Files * Sav&Rest:: Saving and Restoring * Yap4 Notes:: Changes in Foreign Predicates Interface @end menu -@node Manipulating Terms, WritingC, , C-Interface +@node Manipulating Terms, Unifying Terms, , C-Interface @section Terms This section provides information about the primitives available to the C @@ -11775,6 +11798,9 @@ or equal to the arity of the functor. @strong{Note:} all the above primitives returning terms ensure that the result is @i{dereferenced}, i.e. that it is not an instantiated variable. +@node Unifying Terms, Manipulating Strings, Manipulating Terms, C-Interface +@section Unification + The following routine is provided for attempting the unification of two prolog terms @example @@ -11784,6 +11810,9 @@ prolog terms which attempts to unify the terms pointed to by @code{a} and @code{b} returning a non-zero value if the unification succeeds and zero otherwise. +@node Manipulating Strings, Memory Allocation, Unifying Terms, C-Interface +@section Strings + The YAP C-interface now includes an utility routine to copy a string represented as a list of a character codes to a previously allocated buffer @example @@ -11797,6 +11826,19 @@ otherwise the routine will simply fail. The @code{StringToBuffer} routine fails and generates an exception if @code{String} is not a valid string. +The C-interface also includes utility routines to do the reverse, that +is, to copy a from a buffer to a list of character codes or to a list of +character atomsr +@example + Term BufferToString(char *buf) + Term BufferToAtomList(char *buf) +@end example +@noindent +The user-provided string must include a terminating null character. + +@node Memory Allocation, Controlling Streams, Manipulating Strings, C-Interface +@section Memory Allocation + The next routine can be used to ask space from the Prolog data-base: @example void *AllocSpaceFromYap(int size) @@ -11805,7 +11847,7 @@ The next routine can be used to ask space from the Prolog data-base: The routine returns a pointer to a buffer allocated from the code area, or @code{NULL} if no space was available. -Space can be released by using: +This Space can be released by using: @example void FreeSpaceFromYap(void *buf) @end example @@ -11814,9 +11856,51 @@ The routine releases a buffer allocated from the code area. The system may crash if @code{buf} is not a valid pointer to a buffer in the code area. +@node Controlling Streams, Calling Yap From C, Memory Allocation, C-Interface +@section Controlling Yap Streams from @code{C} + +The C-Interface also provides the C-application with a measure of +control over the Yap Input/Output system. The first routine allows one +to find a file number given a current stream: +@example + int YapStreamToFileNo(Term stream) +@end example +@noindent +This function gives the file descriptor for a currently available +stream. Note that null streams and in memory streams do not have +corresponding open streams, so the routine will return a +negative. Moreover, Yap will not be aware of any direct operations on +this stream, so information on, say, current stream position, may become +stale. + +A second routine that is sometimes useful is: +@example + void YapCloseAllOpenStreams(void) +@end example +@noindent +This routine closes the Yap Input/Output system except for the first +three streams, that are always associated with the three standard Unix +streams. It is most useful if you are doing @code{fork()}. + +The next routine allows a currently open file to become a stream. The +routine receives as arguments a file descriptor, the true file name as a +string, an atom with the yser name, and a set of flags: +@example + void YapOpenStream(void *FD, char *true, Term t, int flags) +@end example +@noindent +The available flags are @code{YAP_INPUT_STREAM}, +@code{YAP_OUTPUT_STREAM}, @code{YAP_APPEND_STREAM}, +@code{YAP_PIPE_STREAM}, @code{YAP_TTY_STREAM}, @code{YAP_POPEN_STREAM}, +@code{YAP_BINARY_STREAM}, and @code{YAP_SEEKABLE_STREAM}. By default, the +stream is supposed to be at position 0. + +@node Calling Yap From C, Writing C, Controlling Streams, C-Interface +@section From @code{C} back to Prolog + Newer versions of YAP allow for calling the Prolog interpreter from -@code{C}. One must first construct a goal @code{G}, and then it is sufficient -to perform: +@code{C}. One must first construct a goal @code{G}, and then it is +sufficient to perform: @example Int YapCallProlog(Term G) @end example @@ -11827,7 +11911,7 @@ values they have been unified with. Execution only proceeds until finding the first solution to the goal, but you can call @code{findall/3} or friends if you need all the solutions. -@node WritingC, LoadingO, Manipulating Terms, C-Interface +@node Writing C, Loading Objects, Calling Yap From C, C-Interface @section Writing predicates in C We will distinguish two kinds of predicates: @@ -11885,7 +11969,7 @@ typedef struct @{ n100_data_type *n100_data; @end example -We now write the C function to handle the first call: +We now write the @code{C} function to handle the first call: @example static int start_n100() @@ -11896,11 +11980,11 @@ static int start_n100() n100_data->next_solution = MkIntTerm(0); return(continue_n100()); @} - if(!IsIntTerm(t) || IntOfTerm(t)<0 || IntOfTerm(t)>100) { + if(!IsIntTerm(t) || IntOfTerm(t)<0 || IntOfTerm(t)>100) @{ cut_fail(); - } else { + @} else @{ cut_succeed(); - } + @} @} @end example @@ -11972,7 +12056,7 @@ where @code{name} is a string with the name of the predicate, @code{init} and @code{cont} are the C functions used to start and continue the execution of the predicate, and @code{arity} is the predicate arity. -@node LoadingO, Sav&Rest, WritingC, C-Interface +@node Loading Objects, Sav&Rest, Writing C, C-Interface @section Loading Object Files The primitive predicate @@ -11997,7 +12081,7 @@ for object code (64 Kbytes in the current version). Should this size prove inadequate the flag @code{-c n} can be passed to YAP (in the command line invoking YAP) to force the allocation of @code{n} Kbytes. -@node Sav&Rest, Yap4 Notes, LoadingO, C-Interface +@node Sav&Rest, Yap4 Notes, Loading Objects, C-Interface @section Saving and Restoring @comment The primitive predicates @code{save} and @code{restore} will save and restore