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