version 1.195, 2008/04/28 08:42:59
|
version 1.196, 2008/06/17 21:27:54
|
Line 410 C Interface
|
Line 410 C Interface
|
* Calling C Functions:: |
* Calling C Functions:: |
* Declaring C Functions:: |
* Declaring C Functions:: |
* Calling C function pointers:: |
* Calling C function pointers:: |
|
* Defining library interfaces:: |
|
* Declaring OS-level libraries:: |
* Callbacks:: |
* Callbacks:: |
* C interface internals:: |
* C interface internals:: |
* Low-Level C Interface Words:: |
* Low-Level C Interface Words:: |
Line 12056 as well as a way of declaring structs, u
|
Line 12058 as well as a way of declaring structs, u
|
* Calling C Functions:: |
* Calling C Functions:: |
* Declaring C Functions:: |
* Declaring C Functions:: |
* Calling C function pointers:: |
* Calling C function pointers:: |
* Declaring libraries:: |
* Defining library interfaces:: |
|
* Declaring OS-level libraries:: |
* Callbacks:: |
* Callbacks:: |
* C interface internals:: |
* C interface internals:: |
* Low-Level C Interface Words:: |
* Low-Level C Interface Words:: |
Line 12233 interface; you can find some examples fo
|
Line 12236 interface; you can find some examples fo
|
in @file{lib.fs}. |
in @file{lib.fs}. |
|
|
|
|
@node Calling C function pointers, Declaring libraries, Declaring C Functions, C Interface |
@node Calling C function pointers, Defining library interfaces, Declaring C Functions, C Interface |
@subsection Calling C function pointers from Forth |
@subsection Calling C function pointers from Forth |
@cindex C function pointers, calling from Forth |
@cindex C function pointers, calling from Forth |
|
|
Line 12270 function pointer you want to call from F
|
Line 12273 function pointer you want to call from F
|
a separate calling word. |
a separate calling word. |
|
|
|
|
@node Declaring libraries, Callbacks, Calling C function pointers, C Interface |
@node Defining library interfaces, Declaring OS-level libraries, Calling C function pointers, C Interface |
@subsection Declaring libraries |
@subsection Defining library interfaces |
|
@cindex giving a name to a library interface |
|
@cindex library interface names |
|
|
|
You can give a name to a bunch of C function declarations (a library |
|
interface), as follows: |
|
|
|
@example |
|
c-library lseek-lib |
|
\c #define _FILE_OFFSET_BITS 64 |
|
... |
|
end-c-library |
|
@end example |
|
|
|
The effect of giving such a name to the interface is that the |
|
generated files will contain that name, and when you use the interface |
|
a second time, it will use the existing files instead of generating |
|
and compiling them again, saving you time. Note that even if you |
|
change the declarations, the old (stale) files will be used, probably |
|
leading to errors. So, during development of the declarations we |
|
recommend not using @code{c-library}. |
|
|
|
Note that the library name is not allocated in the dictionary and |
|
therefore does not shadow dictionary names. It is used in the file |
|
system, so you have to use naming conventions appropriate for file |
|
systems. Also, you must not call a function you declare after |
|
@code{c-library} before you perform @code{end-c-library}. |
|
|
|
A major benefit of these named library interfaces is that, once they |
|
are generated, the tools used to generated them (in particular, the C |
|
compiler and libtool) are no longer needed, so the interface can be |
|
used even on machines that do not have the tools installed. |
|
|
|
doc-c-library-name |
|
doc-c-library |
|
doc-end-c-library |
|
|
|
|
|
@node Declaring OS-level libraries, Callbacks, Defining library interfaces, C Interface |
|
@subsection Declaring OS-level libraries |
@cindex Shared libraries in C interface |
@cindex Shared libraries in C interface |
@cindex Dynamically linked libraries in C interface |
@cindex Dynamically linked libraries in C interface |
@cindex Libraries in C interface |
@cindex Libraries in C interface |
|
|
For calling some C functions, you need to link with a specific library |
For calling some C functions, you need to link with a specific |
that contains that library. E.g., the @code{sin} function requires |
OS-level library that contains that function. E.g., the @code{sin} |
linking a special library by using the command line switch @code{-lm}. |
function requires linking a special library by using the command line |
In our C iterface you do the equivalent thing by calling |
switch @code{-lm}. In our C iterface you do the equivalent thing by |
@code{add-lib} as follows: |
calling @code{add-lib} as follows: |
|
|
@example |
@example |
clear-libs |
clear-libs |
Line 12297 declare the function as shown above. Ty
|
Line 12339 declare the function as shown above. Ty
|
set of library declarations for many function declarations; you need |
set of library declarations for many function declarations; you need |
to write only one set for that, right at the beginning. |
to write only one set for that, right at the beginning. |
|
|
|
Note that you must not call @code{clear-libs} inside |
|
@code{c-library...end-c-library}; however, @code{c-library} performs |
|
the function of @code{clear-libs}, so @code{clear-libs} is not |
|
necessary, and you usually want to put @code{add-lib} calls inside |
|
@code{c-library...end-c-library}. |
|
|
doc-clear-libs |
doc-clear-libs |
doc-add-lib |
doc-add-lib |
|
|
|
|
@node Callbacks, C interface internals, Declaring libraries, C Interface |
@node Callbacks, C interface internals, Declaring OS-level libraries, C Interface |
@subsection Callbacks |
@subsection Callbacks |
@cindex Callback functions written in Forth |
@cindex Callback functions written in Forth |
@cindex C function pointers to Forth words |
@cindex C function pointers to Forth words |
Line 12369 function is linked.
|
Line 12417 function is linked.
|
|
|
doc-open-lib |
doc-open-lib |
doc-lib-sym |
doc-lib-sym |
|
doc-lib-error |
doc-call-c |
doc-call-c |
|
|
@c ------------------------------------------------------------- |
@c ------------------------------------------------------------- |