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