Gawk/Extension-API-Functions-Introduction

17.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 chapter.
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. The list of macros and related header files is shown in Table 17.1.

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>`

Table 17.1: Standard header files needed by API

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 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, 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 section presents the macros as if they were functions.