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