Gawk/Extension-API-Boilerplate
Next: Changes from API V1, Previous: Extension API Variables, Up: Extension API Description [Contents][Index]
17.4.14 Boilerplate Code
As mentioned earlier (see section How It Works at a High Level), the function
definitions as presented are really macros. To use these macros, your
extension must provide a small amount of boilerplate code (variables and
functions) toward the top of your source file, using predefined names
as described here. The boilerplate needed is also provided in comments
in the gawkapi.h
header file:
/* Boilerplate code: */ int plugin_is_GPL_compatible; static gawk_api_t *const api;
static awk_ext_id_t ext_id; static const char *ext_version = NULL; /* or … = "some string" */ static awk_ext_func_t func_table[] = { { "name", do_name, 1, 0, awk_false, NULL }, /* … */ }; /* EITHER: */ static awk_bool_t (*init_func)(void) = NULL; /* OR: */ static awk_bool_t init_my_extension(void) { … } static awk_bool_t (*init_func)(void) = init_my_extension; dl_load_func(func_table, some_name, "name_space_in_quotes")
These variables and functions are as follows:
int plugin_is_GPL_compatible;
This asserts that the extension is compatible with the GNU GPL (see section GNU General Public License). If your extension does not have this,
gawk
will not load it (see section Extension Licensing).static gawk_api_t *const api;
This global
static
variable should be set to point to thegawk_api_t
pointer thatgawk
passes to yourdl_load()
function. This variable is used by all of the macros.static awk_ext_id_t ext_id;
This global static variable should be set to the
awk_ext_id_t
value thatgawk
passes to yourdl_load()
function. This variable is used by all of the macros.static const char *ext_version = NULL; /* or … = "some string" */
This global
static
variable should be set either toNULL
, or to point to a string giving the name and version of your extension.static awk_ext_func_t func_table[] = { … };
This is an array of one or more
awk_ext_func_t
structures, as described earlier (see section Registering An Extension Function). It can then be looped over for multiple calls toadd_ext_func()
.static awk_bool_t (*init_func)(void) = NULL;
OR
static awk_bool_t init_my_extension(void) { … }
static awk_bool_t (*init_func)(void) = init_my_extension;
If you need to do some initialization work, you should define a function that does it (creates variables, opens files, etc.) and then define the
init_func
pointer to point to your function. The function should returnawk_false
upon failure, orawk_true
if everything goes well.If you don’t need to do any initialization, define the pointer and initialize it to
NULL
.dl_load_func(func_table, some_name, "name_space_in_quotes")
This macro expands to a
dl_load()
function that performs all the necessary initializations.
The point of all the variables and arrays is to let the
dl_load()
function (from the dl_load_func()
macro) do all the standard work. It does the following:
- Check the API versions. If the extension major version does not match
gawk
’s, or if the extension minor version is greater thangawk
’s, it prints a fatal error message and exits. - Check the MPFR and GMP versions. If there is a mismatch, it prints a fatal error message and exits.
- Load the functions defined in
func_table
. If any of them fails to load, it prints a warning message but continues on. - If the
init_func
pointer is notNULL
, call the function it points to. If it returnsawk_false
, print a warning message. - If
ext_version
is notNULL
, register the version string withgawk
.
Next: Changes from API V1, Previous: Extension API Variables, Up: Extension API Description [Contents][Index]