gforth/doc/gforth.ds - diff

Return to gforth.ds CVS log

Up to [gforth] / gforth / doc

Diff for /gforth/doc/gforth.ds between versions 1.195 and 1.196

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 -------------------------------------------------------------

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.195
changed lines
	Added in v.1.196