Next: General Data Types, Up: Extension API Description [Contents][Index]
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:
Registration functions. You may register:
All of these are discussed in detail later in this chapter.
ERRNO
, or unsetting it.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.
gawk
and/or pass such values to it, you must include the
<mpfr.h>
header before including <gawkapi.h>
.gawkapi.h
file may be included more than once without ill effect.
Doing so, however, is poor coding practice.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.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 multibyteencoding (as defined by
LC_xxx
environment variables) and not using wide characters. This matches howgawk
stores strings internally and also how characters are likely to be input intoand output from files.
NOTE: String values passed to an extension by
gawk
are alwaysNUL-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 ofstrlen()
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.
Next: General Data Types, Up: Extension API Description [Contents][Index]