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