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:
All of these are discussed in detail later in this chapter.
ERRNO, or unsetting it.
Some points about using the API:
|C entity||Header file|
|Values for |
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
gawk source code.
gawkand/or pass such values to it, you must include the
<mpfr.h>header before including
inlinekeyword. 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.
gawkpoint to memory managed by
gawkand should be treated by the extension as read-only.
Memory for all strings passed into
from the extension must come from calling one of
and is managed by
gawk from then on.
Memory for MPFR/GMP values that come from
should also be treated as read-only. However, unlike strings,
memory for MPFR/GMP values allocated by an extension and passed
gawk is copied by
gawk; the extension
should then free the values itself to avoid memory leaks. This is
discussed further in API Ownership of MPFR and GMP Values.
structs 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,
gawkmaintains strings using the current multibyte encoding (as defined by
LC_xxxenvironment variables) and not using wide characters. This matches how
gawkstores strings internally and also how characters are likely to be input into and output from files.
NOTE: String values passed to an extension by
gawkare always NUL-terminated. Thus it is safe to pass such string values to standard library and system routines. However, because
gawkallows 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
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 section presents the macros as if they were functions.