Before you can call a C function, you have to declare it in some way. To spare you the effort of writing the declarations yourself (see Declaring C Functions), Gforth comes with a number of files that contain definitions for many of the commonly-used C functions available in Unix-based systems. They are typically in the files /usr/local/share/gforth/1.0/unix (possibly with /usr/local replaced with some other installation directory, such as /usr, and 1.0 replaced with the Gforth version).
To find whether a function you are interested in has already been
declared, you can search the .fs files in that directory.
E.g., to find the function localtime_r(), you can use
and you will find it defined in unix/time.fs with:
c-function localtime_r localtime_r a a -- a ( time-addr tmaddr -- tmaddr )
Here you see localtime_r twice, first as Forth name, then as C
name. You can now include that file from Gforth with
require unix/time.fs
and then call localtime_r (the Forth name of the C function) in
Forth (see Calling C functions).
The documentation for a C function also applies to the Forth word for the C function.
Some of the files containing the function definitions were written manually (in that case you see a copyright notice at the top), and in some cases contain useful Forth words (that are, however, usually not documented in this manual) in addition to the C functions.
Other files were generated by automatically converting .h files. In that case you see a comment “\ This file has been generated [...]” at the top of the file. These files declare Forth words for all the constants, structures, fields and functions that could be converted from the .h file.