File: gawk.info,  Node: Extension API Boilerplate,  Next: Changes from API V1,  Prev: Extension API Variables,  Up: Extension API Description

17.4.15 Boilerplate Code
------------------------

As mentioned earlier (*note Extension Mechanism Outline::), 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
     (*note Copying::).  If your extension does not have this, 'gawk'
     will not load it (*note Plugin License::).

'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 (*note Extension Functions::).  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:

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

  2. Check the MPFR and GMP versions.  If there is a mismatch, it prints
     a fatal error message and exits.

  3. Load the functions defined in 'func_table'.  If any of them fails
     to load, it prints a warning message but continues on.

  4. If the 'init_func' pointer is not 'NULL', call the function it
     points to.  If it returns 'awk_false', print a warning message.

  5. If 'ext_version' is not 'NULL', register the version string with
     'gawk'.