gawk: Extension API Functions Introduction
1
1 16.4.1 Introduction
1 -------------------
1
1 Access to facilities within 'gawk' is achieved by calling through
1 function pointers passed into your extension.
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:
1
1 - Extension functions
1 - Exit callbacks
1 - A version string
1 - Input parsers
1 - Output wrappers
1 - Two-way processors
1
1 All of these are discussed in detail later in this major node.
1
1 * Printing fatal, warning, and "lint" warning messages.
1
1 * Updating 'ERRNO', or unsetting it.
1
1 * Accessing parameters, including converting an undefined parameter
1 into an array.
1
1 * Symbol table access: retrieving a global variable, creating one, or
1 changing one.
1
1 * Creating and releasing cached values; this provides an efficient
1 way to use values for multiple variables and can be a big
1 performance win.
1
1 * Manipulating arrays:
1
1 - Retrieving, adding, deleting, and modifying elements
1
1 - Getting the count of elements in an array
1
1 - Creating a new array
1
1 - Clearing an array
1
1 - Flattening an array for easy C-style looping over all its
1 indices and elements
1
1 * Accessing and manipulating redirections.
1
1 Some points about using the API:
1
1 * The following types, macros, and/or functions are referenced in
1 'gawkapi.h'. For correct use, you must therefore include the
1 corresponding standard header file _before_ including 'gawkapi.h':
1
1 C entity Header file
1 -------------------------------------------
1 'EOF' '<stdio.h>'
1 Values for 'errno' '<errno.h>'
1 'FILE' '<stdio.h>'
1 'NULL' '<stddef.h>'
1 'memcpy()' '<string.h>'
1 'memset()' '<string.h>'
1 'size_t' '<sys/types.h>'
1 'struct stat' '<sys/stat.h>'
1
1 Due to portability concerns, especially to systems that are not
1 fully standards-compliant, it is your responsibility to include the
1 correct files in the correct way. This requirement is necessary in
1 order to keep 'gawkapi.h' clean, instead of becoming a portability
1 hodge-podge as can be seen in some parts of the 'gawk' source code.
1
1 * If your extension uses MPFR facilities, and you wish to receive
1 such values from 'gawk' and/or pass such values to it, you must
1 include the '<mpfr.h>' header before including '<gawkapi.h>'.
1
1 * The 'gawkapi.h' file may be included more than once without ill
1 effect. Doing so, however, is poor coding practice.
1
1 * Although the API only uses ISO C 90 features, there is an
1 exception; the "constructor" functions use the 'inline' keyword.
1 If your compiler does not support this keyword, you should either
1 place '-Dinline=''' on your command line or use the GNU Autotools
1 and include a 'config.h' file in your extensions.
1
1 * All pointers filled in by 'gawk' point to memory managed by 'gawk'
1 and should be treated by the extension as read-only. Memory for
1 _all_ strings passed into 'gawk' from the extension _must_ come
1 from calling one of 'gawk_malloc()', 'gawk_calloc()', or
1 'gawk_realloc()', and is managed by 'gawk' from then on.
1
1 * The API defines several simple 'struct's that map values as seen
1 from 'awk'. A value can be a 'double', a string, or an array (as
1 in multidimensional arrays, or when creating a new array).
1
1 String values maintain both pointer and length, because embedded
1 NUL characters are allowed.
1
1 NOTE: By intent, 'gawk' maintains strings using the current
1 multibyte encoding (as defined by 'LC_XXX' environment
1 variables) and not using wide characters. This matches how
1 'gawk' stores strings internally and also how characters are
1 likely to be input into and output from files.
1
1 NOTE: String values passed to an extension by 'gawk' are
1 always NUL-terminated. Thus it is safe to pass such string
1 values to standard library and system routines. However,
1 because 'gawk' allows embedded NUL characters in string data,
1 before using the data as a regular C string, you should check
1 that the length for that string passed to the extension
1 matches the return value of 'strlen()' for it.
1
1 * When retrieving a value (such as a parameter or that of a global
1 variable or array element), the extension requests a specific type
1 (number, string, scalar, value cookie, array, or "undefined").
1 When the request is "undefined," the returned value will have the
1 real underlying type.
1
1 However, if the request and actual type don't match, the access
1 function returns "false" and fills in the type of the actual value
1 that is there, so that the extension can, e.g., print an error
1 message (such as "scalar passed where array expected").
1
1 You may call the API functions by using the function pointers
1 directly, but the interface is not so pretty. To make extension code
1 look more like regular code, the 'gawkapi.h' header file defines several
1 macros that you should use in your code. This minor node presents the
1 macros as if they were functions.
1