gawk: Extension summary

1 
1 16.9 Summary
1 ============
1 
1    * You can write extensions (sometimes called plug-ins) for 'gawk' in
1      C or C++ using the application programming interface (API) defined
1      by the 'gawk' developers.
1 
1    * Extensions must have a license compatible with the GNU General
1      Public License (GPL), and they must assert that fact by declaring a
1      variable named 'plugin_is_GPL_compatible'.
1 
1    * Communication between 'gawk' and an extension is two-way.  'gawk'
1      passes a 'struct' to the extension that contains various data
1      fields and function pointers.  The extension can then call into
1      'gawk' via the supplied function pointers to accomplish certain
1      tasks.
1 
1    * One of these tasks is to "register" the name and implementation of
1      new 'awk'-level functions with 'gawk'.  The implementation takes
1      the form of a C function pointer with a defined signature.  By
1      convention, implementation functions are named 'do_XXXX()' for some
1      'awk'-level function 'XXXX()'.
1 
1    * The API is defined in a header file named 'gawkapi.h'.  You must
1      include a number of standard header files _before_ including it in
1      your source file.
1 
1    * API function pointers are provided for the following kinds of
1      operations:
1 
1         * Allocating, reallocating, and releasing memory
1 
1         * Registration functions (you may register extension functions,
1           exit callbacks, a version string, input parsers, output
1           wrappers, and two-way processors)
1 
1         * Printing fatal, nonfatal, warning, and "lint" warning messages
1 
1         * Updating 'ERRNO', or unsetting it
1 
1         * Accessing parameters, including converting an undefined
1           parameter into an array
1 
1         * Symbol table access (retrieving a global variable, creating
1           one, or changing one)
1 
1         * Creating and releasing cached values; this provides an
1           efficient way to use values for multiple variables and can be
1           a big performance win
1 
1         * Manipulating arrays (retrieving, adding, deleting, and
1           modifying elements; getting the count of elements in an array;
1           creating a new array; clearing an array; and flattening an
1           array for easy C-style looping over all its indices and
1           elements)
1 
1    * The API defines a number of standard data types for representing
1      'awk' values, array elements, and arrays.
1 
1    * The API provides convenience functions for constructing values.  It
1      also provides memory management functions to ensure compatibility
1      between memory allocated by 'gawk' and memory allocated by an
1      extension.
1 
1    * _All_ memory passed from 'gawk' to an extension must be treated as
1      read-only by the extension.
1 
1    * _All_ memory passed from an extension to 'gawk' must come from the
1      API's memory allocation functions.  'gawk' takes responsibility for
1      the memory and releases it when appropriate.
1 
1    * The API provides information about the running version of 'gawk' so
1      that an extension can make sure it is compatible with the 'gawk'
1      that loaded it.
1 
1    * It is easiest to start a new extension by copying the boilerplate
1      code described in this major node.  Macros in the 'gawkapi.h'
1      header file make this easier to do.
1 
1    * The 'gawk' distribution includes a number of small but useful
1      sample extensions.  The 'gawkextlib' project includes several more
1      (larger) extensions.  If you wish to write an extension and
1      contribute it to the community of 'gawk' users, the 'gawkextlib'
1      project is the place to do so.
1