Extension API Boilerplate (The GNU Awk User’s Guide)

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 the gawk_api_t pointer that gawk passes to your dl_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 that gawk passes to your dl_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 to NULL, 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 to add_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 return awk_false upon failure, or awk_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 than gawk’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 not NULL, call the function it points to. If it returns awk_false, print a warning message.
If ext_version is not NULL, register the version string with gawk.